Skip to main content

WebPush publication library

Project description

Build Status Requirements Status

Webpush Data encryption library for Python

This is a work in progress. This library is available on pypi as pywebpush. Source is available on github.


You’ll need to run python virtualenv. Then

bin/pip install -r requirements.txt
bin/python develop


In the browser, the promise handler for registration.pushManager.subscribe() returns a PushSubscription object. This object has a .toJSON() method that will return a JSON object that contains all the info we need to encrypt and push data.

As illustration, a subscription_info object may look like:

  "endpoint": "",
  "keys": { "auth": "k8J...", "p256dh": "BOr..." }

How you send the PushSubscription data to your backend, store it referenced to the user who requested it, and recall it when there’s a new push subscription update is left as an exercise for the reader.

Sending Data using webpush() One Call

In many cases, your code will be sending a single message to many recipients. There’s a “One Call” function which will make things easier.

from pywebpush import webpush

        vapid_private_key="Private Key or File Path[1]",
        vapid_claims={"sub": "mailto:YourEmailAddress"})

This will encode data, add the appropriate VAPID auth headers if required and send it to the push server identified in the subscription_info block.


subscription_info - The dict of the subscription info (described above).

data - can be any serial content (string, bit array, serialized JSON, etc), but be sure that your receiving application is able to parse and understand it. (e.g. data = "Mary had a little lamb.")

content_type - specifies the form of Encryption to use, either 'aes128gcm' or the deprecated 'aesgcm'. NOTE that not all User Agents can decrypt 'aesgcm', so the library defaults to the RFC 8188 standard form.

vapid_claims - a dict containing the VAPID claims required for authorization (See py_vapid for more details). If aud is not specified, pywebpush will attempt to auto-fill from the endpoint.

vapid_private_key - Either a path to a VAPID EC2 private key PEM file, or a string containing the DER representation. (See py_vapid for more details.) The private_key may be a base64 encoded DER formatted private key, or the path to an OpenSSL exported private key file.

e.g. the output of:

openssl ecparam -name prime256v1 -genkey -noout -out private_key.pem


from pywebpush import webpush, WebPushException

            "endpoint": "",
            "keys": {
                "p256dh": "0123abcde...",
                "auth": "abc123..."
        data="Mary had a little lamb, with a nice mint jelly",
                "sub": "",
except WebPushException as ex:
    print("I'm sorry, Dave, but I can't do that: {}", repr(ex))
    # Mozilla returns additional information in the body of the response.
    if ex.response and ex.response.json():
        extra = ex.response.json()
        print("Remote service replied with a {}:{}, {}",


If you expect to resend to the same recipient, or have more needs than just sending data quickly, you can pass just wp = WebPusher(subscription_info). This will return a WebPusher object.

The following methods are available:

.send(data, headers={}, ttl=0, gcm_key="", reg_id="", content_encoding="aes128gcm", curl=False, timeout=None)

Send the data using additional parameters. On error, returns a WebPushException


data Binary string of data to send

headers A dict containing any additional headers to send

ttl Message Time To Live on Push Server waiting for the client to reconnect (in seconds)

gcm_key Google Cloud Messaging key (if using the older GCM push system) This is the API key obtained from the Google Developer Console.

reg_id Google Cloud Messaging registration ID (will be extracted from endpoint if not specified)

content_encoding ECE content encoding type (defaults to “aes128gcm”)

curl Do not execute the POST, but return as a curl command. This will write the encrypted content to a local file named This command is meant to be used for debugging purposes.

timeout timeout for requests POST query. See requests documentation.


to send from Chrome using the old GCM mode:

WebPusher(subscription_info).send(data, headers, ttl, gcm_key)
.encode(data, content_encoding="aes128gcm")

Encode the data for future use. On error, returns a WebPushException


data Binary string of data to send

content_encoding ECE content encoding type (defaults to “aes128gcm”)


encoded_data = WebPush(subscription_info).encode(data)

Stand Alone Webpush

If you’re not really into coding your own solution, there’s also a “stand-alone” pywebpush command in the ./bin directory.

This uses two files:

  • the data file, which contains the message to send, in whatever form you like.

  • the subscription info file, which contains the subscription information as JSON encoded data. This is usually returned by the Push subscribe method and looks something like:

  "endpoint": "https://push...",
  "keys": {
    "auth": "ab01...",
    "p256dh": "aa02..."

If you’re interested in just testing your applications WebPush interface, you could use the Command Line:

./bin/pywebpush --data --info

which will encrypt and send the contents of

See ./bin/pywebpush --help for available commands and options.

# I am terrible at keeping this up-to-date.

## 1.14.0 (2021-07-28) bug: accept all VAPID key instances (thanks @mthu)

## 1.13.0 (2021-03-15) Support requests_session param in webpush fn too

## 1.12.0 (2021-03-15) chore: library update, remove nose tests

## 1.11.0 (2020-04-29) feat: add –head to read headers out of a json file (thanks @braedon)

## 1.10.2 (2020-04-11) bug: update min vapid requirement to 1.7.0

## 1.10.1 (2019-12-03) feat: use six.text_type instead of six.string_types

## 1.10.0 (2019-08-13) feat: Add –verbose flag with some initial commentary bug: Update tests to use latest VAPID version

## 1.9.4 (2019-05-09) bug: update vapid exp header if missing or expired

## 0.7.0 (2017-02-14) feat: update to http-ece 0.7.0 (with draft-06 support) feat: Allow empty payloads for send() feat: Add python3 classfiers & python3.6 travis tests feat: Add README.rst bug: change long to int to support python3

## 0.4.0 (2016-06-05) feat: make python 2.7 / 3.5 polyglot

## 0.3.4 (2016-05-17) bug: make header keys case insenstive

## 0.3.3 (2016-05-17) bug: force key string encoding to utf8

## 0.3.2 (2016-04-28) bug: fix issues

## 0.3 (2016-04-27) feat: added travis, normalized directories

## 0.2 (2016-04-27) feat: Added tests, restructured code

## 0.1 (2016-04-25)

Initial release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pywebpush-1.14.0.tar.gz (25.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page