Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

WebPush publication library

Project Description

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 'aesgcm' or the newer 'aes128gcm'. NOTE that not all User Agents can decrypt 'aes128gcm', so the library defaults to the older 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))


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="aesgcm", 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 “aesgcm”)

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="aesgcm")

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 “aesgcm”)


encoded_data = WebPush(subscription_info).encode(data)

## 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

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pywebpush-1.1.0.tar.gz (19.2 kB) Copy SHA256 Checksum SHA256 Source Jul 26, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting