Managing Push Subscriptions

This article is a continuing series about using and working with WebPush and Mozilla’s WebPush service. This article is not meant to be a general guide, but instead offer suggestions and insight into best using the service. Some knowledge of Javascript, Python, or other technologies is presumed.

Sending out push notifications to Customers is a great way to ensure that they’re up-to-date with information that is of importance to them. What’s also important is that your growing business use this service efficiently so you don’t wind up wasting money creating and sending out messages that no one will ever read. In addition, not honoring response codes could lead to your server being blocked or severely limited in how many Subscription Updates it may be able to send.

Mozilla’s WebPush server will let you know if a Customer has unsubscribed, but it’s important that you notice and act on these. I have created a simple demonstration program that can help you understand what you will need to consider when creating a Push Subscription service.


First off, let’s refresh a few terms we’ll use in this article:

App – The javascript web application that receives the decoded Push Message.

Customer – The end recipient of the Push Message.

Push Message – The content of the Subscription Update to be provided to the App by the User Agent and potentially viewed by the Customer.

Push Server – The service located at the endpoint URL which handles delivery of the Subscription Update to the User Agent.

Subscription – A Customer request to be updated. A Subscription contains an endpoint URL, and a set of keys that are to be used to encode the Push Message.

Subscription Provider – The subscription provider sends out Push Messages to User Agents to be read by Customers.

Subscription Update – The message sent by the Subscription Provider to the Push Server.

User Agent – The Customer’s browser, specifically, code internal to the browser which processes and routes Push Messages to your App.

Sending Subscription Updates

Sending a Push Message is a fairly simple operation, and thanks to modern libraries, easily done. It’s important to pay attention to the returned result. When a Subscription Provider sends a Subscription Update, the Push Service returns a response code. In most cases, the response code will be either 201 (Message Created) or 202 (Message Accepted). There’s subtle differences between those, but those differences are not important right now.

What is important is to know that the Push Server will return an HTTP error code along with a body that has extra information about what may have happened.

A possible 404 return message body might look like:
'errno': 102,
'message': 'Request did not validate invalid token',
'code': 404,
'more_info': '',
'error': 'Not Found'

In this case, there was a problem with the URL. More than likely it was corrupted at some point. In any case, the URL is now invalid and should not be tried again. The Customer’s record can be safely removed from storage.

This is also true for 410 return codes. These are subscribers who no longer wish to receive your updates. A Customer may unsubscribe for any number of reasons, and you should respect that choice. You can always ask the Customer to resubscribe later.

The Demo App

As an example, I’ve created a very simple demonstration project that uses Python3. This project does require Python3 to take advantage of native async programming to speed up delivery and message handling. Follow the steps in the README file to get it started. You can then navigate to http://localhost:8200 to see the page.

The test page (located in the /page directory) is very simple and only starts the process of subscribing once the Customer has requested it. Clicking the one button on the page will automatically create a Subscription Request and offer some script snippets you can use to send messages to the App.

To see what happens when a user unsubscribes, disable the permissions using the page information pip:
An example of using the page information pip to unregister from WebPush messages

If you try to send a Subscription Update to that customer again, you will receive an error and should drop the subscription. An example error from pusher may look like:

Failed to send to HMV192av: No such subscription
For more info, see:
Dropping no longer valid user: HMV192av

In this case, the subscription for user HMV192av has been removed, and the record was dropped from the user database.

It’s important to only ask your Customers to subscribe once they understand what they’re subscribing to. A Customer who is asked to subscribe to WebPush notifications without being given a clear indication of what they’re being offered may click the “Always Block Notifications” option. An example of a user blocking WebPush message subscription

When a user blocks notifications from your site, you may never get a chance to ask them again.

Following these simple guidelines will ensure that both you and your Customers are happy using the WebPush service.