Web Push: what is an endpoint?

If you are implementing web push notifications on a website you should be familiar with the concept of endpoint.

First, a website asks the user to subscribe to notifications by displaying a permission prompt.

If a user accepts to receive the notifications, the browser contacts its own push service (e.g. Mozilla autopush for Firefox, FCM for Chrome, etc.) to generate a new push subscription.

The push subscription is associated to that specific website (domain): when the browser visits a different website that asks for notifications, it will always return a different push subscription.

As defined by the Push API, a push subscription is a JavaScript object (JSON) that contains:

  • an endpoint
  • two keys, named “p256dh” and “auth“.

The endpoint is a secret URL which can be used to send push notifications to the current browser.

The keys are used to encrypt the payload, so that only the current browser can read (decrypt) the content of notifications.

A website can generate the endpoint and the keys by calling PushManager.subscribe() and then, when the JavaScript promise is resolved, it should send the subscription to a backend, in order to store it in a database (then the push subscriptions will be used in order to send the notifications).

Here’s an example of endpoint:


As you can see, the first part of the endpoint (URL) represents the browser push service. In this case the push service is FCM, so the browser is probably Google Chrome (or another Chromium based browser). If it was Mozilla Firefox you would probably get an endpoint that starts with “https://updates.push.services.mozilla.com/“.

The last part of the endpoint (URL) is a random token that identify the current browser / device: when your application sends a push message (HTTP POST request) to that endpoint (URL) the push service will be able to deliver the message to the right device (i.e. the push service stores the message, until a browser connects to it and asks to get the notifications for a specific endpoint).

For privacy reasons, in order to avoid cross-site tracking using the device token, the endpoint is completely different for each website (the browser never returns the same subscription for multiple domains).

Basically an endpoint is always random and unique. If you visit another domain you get a different endpoint. If you change browser or device you get a different endpoint. If you erase browser data or you block the notifications and then you allow them again, you will get a different endpoint. The browser can also choose to change the endpoint at any time.

However if you simply change IP address, open another browser tab, you close and reopen a website, etc. the endpoint remains the same.

Finally, when the user decides to revoke the permission for a website, the browser contacts its push service and deletes the endpoint. From that moment, a request to the endpoint will return 410 Gone (see also the error codes) and your application should remove the push subscription from the database (it’s not longer useful).

If you are looking for a Backend-as-a-Service for web push notifications you can use Pushpad. Pushpad manages the push subscriptions, the backend and all the edge-cases for you: you just need to install the JavaScript SDK and call pushpad('subscribe'). By using Pushpad you can forget about the low-level details of Web Push and focus only on your application. You are also free to export all your endpoints and push subscriptions at any time.

Leave a Comment