Definition

PushSubscription

Short definition

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.

Reviewed August 2, 2026

A serialized subscription looks roughly like {"endpoint": "https://fcm.googleapis.com/fcm/send/abc123...", "keys": {"p256dh": "BN4G...", "auth": "tBHI..."}}, and this whole object — not just the endpoint — must be stored, since both keys are required to encrypt the payload correctly.

Subscriptions can expire or be revoked by the user (e.g. clearing site data, uninstalling the PWA, or the browser rotating the endpoint) — a 404 or 410 response from the push service when sending indicates the subscription is dead and should be deleted from your database.

pushSubscription.unsubscribe() lets the page programmatically end a subscription, which your app should call and sync to the server whenever the user turns off notifications in their settings, to avoid sending to a subscription nobody wants anymore.

Because the endpoint is vendor-specific (fcm.googleapis.com, updates.push.services.mozilla.com, etc.), your sending code needs a generic web-push library rather than hardcoding logic for one push service.

Related terms

Push API

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.

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.

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.