Definition

Push API

Short definition

The Push API lets a service worker subscribe to a browser-run push service and receive encrypted messages from a server at any time, including when no tab or window for the site is open. Subscribing is done with registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey }), and incoming messages arrive in the worker's push event.

Reviewed August 1, 2026

userVisibleOnly: true is effectively mandatory on Chromium browsers, which enforce a policy that every push message must result in a visible notification to the user — silent, undetectable background pushes are not permitted by the platform.

The applicationServerKey passed to subscribe() is your VAPID public key, converted to a Uint8Array; it cryptographically ties the subscription to your specific server so only you can send messages to it.

Push delivery is handled by browser-vendor infrastructure (e.g. FCM for Chrome, Mozilla's push service for Firefox), not by your own server directly — your server sends an encrypted request to the subscription's endpoint URL, and the vendor's service relays it to the device.

The full API is specified by the W3C Push API spec and documented on MDN: https://developer.mozilla.org/en-US/docs/Web/API/Push_API.

Related terms

VAPID

VAPID (Voluntary Application Server Identification) is a key-pair scheme, standardised in RFC 8292, where a server generates one ECDSA P-256 key pair, keeps the private key secret, and shares the public key with browsers via the applicationServerKey option when subscribing. It lets push services verify which application server is sending a given message without requiring a proprietary developer account per browser vendor.

PushSubscription

A PushSubscription is the object returned by pushManager.subscribe(), containing an endpoint (a unique, vendor-hosted URL that identifies this specific device/browser installation) and a keys object with p256dh and auth values used to encrypt messages sent to it. Your server stores this per user and sends future notifications by POSTing an encrypted payload to subscription.endpoint.

push event (service worker)

The push event fires on the service worker whenever a message arrives from the push service the browser is subscribed to. A handler typically reads event.data.json() for the payload and calls event.waitUntil(self.registration.showNotification(title, options)) so the browser keeps the worker alive until the notification is actually displayed.

badge (Notification option)

badge is a field passed to showNotification(title, { badge: "/badge-72.png", ... }) that supplies a small, typically monochrome PNG icon (recommended around 72x72 or 96x96) shown in the Android status bar and shade, as distinct from the larger icon field used for the main notification image.

actions (Notification option)

actions is an array option passed to showNotification(), e.g. { actions: [{ action: "reply", title: "Reply" }, { action: "dismiss", title: "Dismiss" }] }, that renders extra buttons on the notification itself. The service worker's notificationclick handler reads event.action to see which button, if any, the user pressed.

tag (Notification option)

tag is a string option, e.g. showNotification("New message", { tag: "chat-thread-42" }), used to identify a class of related notifications. When a new notification arrives with a tag matching one already showing, the browser replaces it in place by default rather than adding a second, separate notification to the shade.