Articles › Technical Insights, Web Push Notifications

Web Push Notifications: Standard and Official Documentation

  • # push-api
  • # service-worker
  • # vapid
  • # web-notifications

"Web Push Notifications" is a general term to refer to the push notifications sent by websites and web apps. However, if you are looking for an official document that defines the "Web Push Notifications" standard, you won't find it. This is because this technology is made up of different technologies, each one serving to a specific purpose. Let's find out what these technologies are and where the official standards are located (documentation).

Push API

The Push API is the standard that defines how to send a push message to a browser.

The push messages are sent from the application server (i.e. website backend) through a push service (provided by the browser company). The browsers are constantly connected to their push service and in this way the notifications can be delivered immediately even when a website is closed (e.g. the user is offline).

The Push API describes how the website should ask for permission before sending notifications.

The Push API also describes the subscription process: when a user accepts to receive the notifications from a website, the browser contacts his own push service to generate a new push subscription and this push subscription is passed to the website (resolving a JavaScript promise).

A push subscription contains a secret endpoint (a URL with a random, unique token) that will be used to deliver the notifications to that specific browser. It also includes a cryptographic key that will be necessary to encrypt the content of the notifications (all push messages MUST be encrypted and can only be decrypted by the browser).

One of the most important methods defined by the Push API is PushManager.subscribe(), which allows to subscribe the users to notifications.

Standard (official documentation): https://www.w3.org/TR/push-api/

Service Workers

In order to receive and display the notifications, a website must register a Service Worker.

The Push API can simply deliver a push message to a website in background, but it doesn't display anything. So the website must read the push message and do something with it (i.e. show a notification to the user). Since the website is not necessarily open when you receive a push message, you need to handle it in background.

A service worker is a JavaScript script that is installed by a website on a device and can be activated by the browser when a push message is received (service workers are not used only for push messages, but this is definitely a major use case).

One of the methods that you will definitely use is ServiceWorkerContainer.register(), in order so register (i.e. install) the service worker script on the user browser.

Standard (official documentation): https://www.w3.org/TR/service-workers/

Web Notifications

Web Notifications are the actual notifications (UI) displayed to the user.

Basically the standard that defines how to display a notification that looks like a native notification (outside the browser window).

A notification has a title, a message, an icon, an image, some action buttons and much more. It has also some events that you should handle (e.g. notificationclick event).

Note that a website can display some web notifications even without the Push API: however that would work only if the website is open. If you use the Push API in conjunction with web notifications you can deliver and display the notifications at any time.

In particular you will probably want to use the ServiceWorkerRegistration.showNotification() method in order to display a notification to the user (i.e. when a push message is received by the service worker).

Standard (official documentation): https://notifications.spec.whatwg.org

Web Push

The WEBPUSH Protocol (RFC 8030) defined by the IETF is the protocol used by the application server to deliver a push message to the push service. Basically it defines in detail how the communication between a website backend and a push service should take place.

The Push API is more focused on the client side (the interactions between the frontend and the browser), while it explicitly mentions the WEBPUSH Protocol for the communications between the backend and the push service.

Standard (official documentation): https://datatracker.ietf.org/doc/html/rfc8030


VAPID (Voluntary Application Server Identification) is a protocol to add an additional layer of security to the notification subscriptions.

Basically, when a push subscription is created, the website can pass a VAPID public key that will be associated to the subscription. Then the subscription can be used to deliver the notifications only by someone that knows the VAPID private key. All push messages sent through the WEBPUSH Protocol will include a VAPID header / signature.

Standard (official documentation): https://datatracker.ietf.org/doc/html/rfc8292

Other useful resources

The Mozilla Developer Network (MDN) has very good documentation about the Push API and all related standards.

If you are looking for a managed service for web push notifications you can use Pushpad: it is easier to implement and offers an additional layer of abstraction, with many additional features that the Push API doesn't offer directly (e.g. user targeting or tag-based routing for notifications, a scalable infrastructure for sending notifications in bulk, scheduled notifications, dashboard, analytics, powerful libraries and JavaScript SDK and much more).