Push Notifications in Progressive Web Apps¶

Web push lets your server deliver a message to a user's browser at any time, even when no tab of your app is open: the browser wakes your service worker, which decrypts the payload and shows a system notification. It is the only standard, cross-browser way for a PWA to re-engage users from the background, and it runs in Chrome, Edge, Firefox and Samsung Internet on desktop and Android, in Safari on macOS, and in Home Screen web apps on iOS and iPadOS. This page walks through every moving part in production detail: the protocol actors, permission UX, PushManager.subscribe(), the PushSubscription object, server-side storage, sending with Node.js and Python, the push and notificationclick handlers, subscription churn, payload and delivery limits, and how to test all of it.

How web push works: the four actors¶

Web push is a composition of three IETF RFCs and two W3C/WHATWG specifications. The Push API defines the JavaScript surface (PushManager, PushSubscription, the push event). RFC 8030 defines the HTTP protocol between your server and the push service. RFC 8291 defines how payloads are encrypted end to end, and RFC 8292 (VAPID) defines how your server proves its identity. The Notifications API turns a message into something the user can see. The byte-level details of the protocol, encryption and JWT signing live on The Web Push Protocol; this page focuses on building a working system.

The browser, not your origin, chooses the push service. You cannot choose or configure it, which is why your server must speak the standard protocol to several of them:

Treat the endpoint as an opaque URL. Mozilla's autopush documentation reserves the right to change any part of it and warns against storing only the last path segment. Store and use the full string exactly as the browser gave it to you.

The complete message flow¶

sequenceDiagram
    autonumber
    actor User
    participant Page
    participant SW as Service worker
    participant UA as Browser push client
    participant PS as Push service
    participant App as Application server
    Page->>App: GET VAPID public key
    User->>Page: clicks "Notify me"
    Page->>UA: pushManager.subscribe(options)
    UA->>User: permission prompt
    User-->>UA: Allow
    UA->>PS: create subscription with applicationServerKey
    PS-->>UA: endpoint URL
    UA-->>Page: PushSubscription with endpoint, p256dh, auth
    Page->>App: POST subscription JSON
    Note over App: later, something happens
    App->>App: encrypt payload and sign VAPID JWT
    App->>PS: POST endpoint with TTL, Urgency, Topic
    PS-->>App: 201 Created
    PS->>UA: deliver when the device is reachable
    UA->>UA: decrypt with the subscription private key
    UA->>SW: start worker and dispatch push
    SW->>User: showNotification()
    User->>SW: clicks the notification
    SW->>Page: focus() or openWindow(url)

A 201 Created from the push service means accepted, not delivered. RFC 8030 lets you request a delivery receipt with Prefer: respond-async, but Mozilla's autopush documents that it cannot support receipts and only returns 201, and none of the major services gives you reliable end-to-end delivery confirmation. If you need to know that a user saw a message, have the service worker report back (see the notificationclose and click handlers below).

What each party can see¶

The payload is encrypted with keys that only the browser holds, so the push service cannot read it. The Push API specification is explicit about what still leaks: the push service sees the timing, frequency and size of your messages, and the only mitigation it names is padding the payload. It also sees the Topic header, which RFC 8030 says is neither encrypted nor authenticated. Do not put user data in topics. Some libraries pad for you: the Go library webpush-go pads every message to a full 4,096-byte record by default, while web-push for Node.js and pywebpush send the minimum size.

The push service also knows your VAPID public key, the sub contact in your JWT, and which endpoint (which browser installation) each message targets. The endpoint itself must not expose information about the user, per the spec, and a deactivated endpoint must never be reused for a new subscription, so an endpoint is a stable pseudonymous identifier of one browser profile for one origin. Treat it as personal data in your storage and logs.

Delivery is best-effort¶

Once accepted, a message is stored by the push service until the device connects or TTL elapses, whichever comes first. The browser acknowledges the message after dispatching it. If the push event fails (a rejected waitUntil() promise), the spec lets the browser refuse the acknowledgment so the push service retries, and recommends allowing at least three attempts before acknowledging a message that keeps failing. A message whose payload fails to decrypt is acknowledged and dropped without any push event, so a key mismatch on your server is silent on the client.

Prerequisites and feature detection¶

Push has more preconditions than most web APIs. All of these must hold before subscribe() can succeed:

On Apple platforms, Lockdown Mode also disables the Push API and Notifications: WebKit marks both features as disabled in Lockdown Mode. Android WebView does not support the Push API at all, so a PWA wrapped in a plain WebView cannot use it; a Trusted Web Activity runs in the full browser and can.

Detect features, not browsers. The one place where a user-agent check is justified is iOS guidance: when PushManager or Notification is missing and the device looks like an iPhone or iPad, tell the user to add the app to the Home Screen instead of saying "your browser is not supported". The full iOS story, including Declarative Web Push and Focus integration, is on Web Push on iOS & Safari.

VAPID keys: your server's identity¶

Voluntary Application Server Identification (RFC 8292) binds a subscription to a key pair that you own. When the browser subscribes, it passes your public key to the push service. From then on the push service accepts messages for that endpoint only if they carry a JWT signed with the matching private key. Anyone who steals subscription endpoints without your private key cannot send to them.

The key pair is an ECDSA key on the P-256 curve:

• The public key is an uncompressed point: 65 bytes starting with 0x04, which is 87 characters in unpadded base64url. It goes into applicationServerKey in the browser and into the k= parameter of the Authorization: vapid t=..., k=... header.
• The private key is a 32-byte scalar, 43 characters in unpadded base64url. It never leaves your server.

Generate a pair once per environment with the web-push CLI, which prints both keys in base64url:

npx web-push generate-vapid-keys --json
# {"publicKey":"BLc4xRzKlKORKWlbdgFaBrrPK3ydWAHo4M0gs0i1oEKgPpWC5cW8OCzVrOQRv-1npXRWk8udnW3oYhIO4475rds","privateKey":"..."}

Store the private key in your secret manager, not in the repository. Both web-push and pywebpush accept the raw base64url private key produced above (pywebpush also accepts a PEM file or DER string).

Rotating VAPID keys¶

A subscription is permanently bound to the applicationServerKey it was created with. The spec says options of an existing subscription cannot change, and calling subscribe() with a different key while a subscription exists rejects with InvalidStateError. Chrome's message spells out the fix: "A subscription with a different applicationServerKey (or gcm_sender_id) already exists; to change the applicationServerKey, unsubscribe then resubscribe." Rotation is therefore a client-side migration:

1. Publish the new public key with a new key ID from your key endpoint, and keep the old private key on the server.
2. Store which key ID each subscription was created with (the vapid_key_id column below), and sign each message with the matching private key.
3. On each page load, compare subscription.options.applicationServerKey with the current key. If they differ, unsubscribe() and subscribe again. Where permission is already granted, Chrome allows this without a prompt; engines that require a user gesture for subscribe() may need a button press.
4. Retire the old private key once no active subscriptions reference it.

Never rotate by simply replacing the key on the server: every existing subscription then fails with 401 or 403 until users happen to revisit, and Safari users whose subscriptions go unrenewed are lost.

Asking for permission without burning it¶

Push permission and notification permission are the same decision in every shipping engine: calling pushManager.subscribe() shows the notification prompt if needed, and granting it grants both. The permission has three states, exposed as Notification.permission ("default", "granted", "denied") and through registration.pushManager.permissionState({ userVisibleOnly: true }) or navigator.permissions.query({ name: "notifications" }) ("prompt", "granted", "denied").

"denied" is effectively permanent. Once a user clicks Block, no API can prompt again; only the user can reset it from site settings. That makes the first prompt the most valuable interaction you have, and browsers actively police how you use it:

The pattern that works everywhere is a two-step opt-in:

1. Show your own in-page UI at a moment when notifications are obviously useful: after the user follows a thread, sets a price alert, or places an order. Explain what you will send and how often.
2. Only when the user clicks your "Turn on notifications" button, call subscribe(). The native prompt now answers a question the user already said yes to.

If the user dismisses your in-page UI, you have lost nothing and can ask again later. Never trigger the native prompt on page load, on scroll, or from a timer. The Permissions page covers permission state tracking across all capabilities, and App-Like UX Patterns covers prompt design.

Subscribing: PushManager.subscribe() in depth¶

PushManager is available as registration.pushManager on a ServiceWorkerRegistration, in both pages and workers. Safari 18.4 and later also expose window.pushManager for Declarative Web Push, which subscribes without any service worker. Its IDL is small:

[Exposed=(Window,Worker), SecureContext]
interface PushManager {
  [SameObject] static readonly attribute FrozenArray<DOMString> supportedContentEncodings;
  Promise<PushSubscription> subscribe(optional PushSubscriptionOptionsInit options = {});
  Promise<PushSubscription?> getSubscription();
  Promise<PermissionState> permissionState(optional PushSubscriptionOptionsInit options = {});
};

dictionary PushSubscriptionOptionsInit {
  boolean userVisibleOnly = false;
  (BufferSource or DOMString)? applicationServerKey = null;
};

The two options¶

userVisibleOnly is a promise from you to the browser: every push message sent to this subscription will result in something the user can see, normally a notification. The spec leaves enforcement to the browser, and in practice Chrome, Edge and Safari refuse subscriptions without it. Firefox accepts either value but does not expose the option at all (subscription.options.userVisibleOnly is undefined there), because it enforces a quota instead. Always pass true.

applicationServerKey is your VAPID public key as a BufferSource (typically a Uint8Array of 65 bytes) or a base64url string. String support was added later (Chrome 76), Chrome rejects padded base64url with InvalidCharacterError, and some older engines only accept buffers, so decoding the key to a Uint8Array yourself is the most portable choice. The spec requires the key to be a valid P-256 point, and different from the ECDH key used for message encryption.

What subscribe() does, step by step¶

The Push API algorithm, condensed:

1. If the PushManager belongs to a Window (Declarative Web Push), the scope is the origin's root /. Otherwise the scope is the registration's scope.
2. If the scope's scheme is not https, reject with NotAllowedError. (Chromium-based browsers nevertheless allow http://localhost during development.)
3. If userVisibleOnly is false and the browser requires true, reject with NotAllowedError.
4. If applicationServerKey is null and the push service requires one, reject with NotSupportedError.
5. If the key is a string, base64url-decode it; on failure reject with InvalidCharacterError. If the bytes are not a valid P-256 point, reject with InvalidAccessError.
6. In parallel: if the registration has no active worker, reject with InvalidStateError. Look up the existing subscription for this scope.
7. Request permission to use "push". If the result is "denied", reject with NotAllowedError.
8. If a subscription exists: reject with AbortError if it is in an error state, reject with InvalidStateError if its options differ from the ones passed (buffers are compared by content), and otherwise resolve with the existing subscription.
9. Otherwise create a subscription: generate a new P-256 ECDH key pair and a 16-byte auth secret (RFC 8291), request an endpoint from the push service including your applicationServerKey, and resolve with the new PushSubscription.

Step 8 is what makes subscribe() idempotent: calling it again with identical options returns the same subscription and endpoint, so it is safe to call on every visit when permission is already granted.

Exceptions and what they mean in practice¶

getSubscription() and permissionState()¶

getSubscription() resolves with the registration's current subscription or null, never prompts, and does not need a user gesture. Use it on every page load to render the right UI state and to re-sync the subscription with your server.

permissionState(options) resolves with "prompt", "granted" or "denied" for the push permission without prompting. Pass { userVisibleOnly: true }: the Permissions API defines {name: "push", userVisibleOnly: false} as a stronger permission than the user-visible one, and browsers that do not grant silent push report the stronger one differently.

PushManager.supportedContentEncodings lists the payload encodings the browser can decrypt. Every engine must support aes128gcm (RFC 8291). Chrome still lists the pre-standard aesgcm as well; Firefox has stopped advertising aesgcm by default, although it can still decrypt it. Always send aes128gcm.

Production client code¶

This module separates the three things the UI needs: a capability report, a startup routine that never prompts, and an opt-in function that must run inside a click handler. It handles key rotation, re-syncs on every visit and keeps the user activation intact.

// push-client.js: page-side subscription management (ES module).
const API = {
  publicKey: "/api/push/vapid-public-key",
  subscriptions: "/api/push/subscriptions",
};

let registration = null; // resolved once at startup, never inside a click handler
let vapidKey = null; // { id, bytes } prefetched so subscribe() runs inside the gesture

/** Capability report used to decide which UI to render. */
export function getPushCapability() {
  const secure = window.isSecureContext;
  const hasSW = "serviceWorker" in navigator;
  const hasPush = "PushManager" in window;
  const hasNotification = "Notification" in window;
  const standalone =
    window.matchMedia("(display-mode: standalone)").matches ||
    navigator.standalone === true; // legacy iOS flag
  // UA sniffing is used ONLY to show "add to Home Screen" guidance, never to gate the API.
  const looksLikeIOS =
    /iPad|iPhone|iPod/.test(navigator.userAgent) ||
    (/Macintosh/.test(navigator.userAgent) && navigator.maxTouchPoints > 1);

  if (!secure || !hasSW) return { supported: false, reason: "insecure-or-no-sw" };
  if (hasPush && hasNotification) return { supported: true, standalone };
  if (looksLikeIOS && !standalone) return { supported: false, reason: "ios-needs-home-screen" };
  return { supported: false, reason: "no-push-api" };
}

/** Call once on page load. Never prompts. Returns the current UI state. */
export async function initPush() {
  const capability = getPushCapability();
  if (!capability.supported) return { state: "unsupported", reason: capability.reason };

  registration = await navigator.serviceWorker.ready;
  vapidKey = await fetchVapidKey();

  if (Notification.permission === "denied") return { state: "blocked" };

  const subscription = await registration.pushManager.getSubscription();
  if (!subscription) {
    return { state: Notification.permission === "granted" ? "granted-unsubscribed" : "prompt" };
  }

  // The server key changed (rotation): the old subscription can no longer be used.
  if (!sameBytes(subscription.options.applicationServerKey, vapidKey.bytes)) {
    await subscription.unsubscribe().catch(() => {});
    await deleteOnServer(subscription.endpoint).catch(() => {});
    return { state: "granted-unsubscribed" };
  }

  // Re-send on every load: cheap, idempotent, and repairs any server-side loss.
  await saveOnServer(subscription).catch((err) => console.warn("push sync failed", err));
  return { state: "subscribed" };
}

/** Must be called synchronously from a click/tap handler. */
export async function enablePush() {
  if (!registration || !vapidKey) throw new Error("initPush() has not completed");
  let subscription;
  try {
    // First await in the handler: keeps the transient user activation intact.
    subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: vapidKey.bytes,
    });
  } catch (err) {
    if (err.name === "NotAllowedError") {
      return { state: Notification.permission === "denied" ? "blocked" : "prompt" };
    }
    if (err.name === "InvalidStateError") {
      // An existing subscription was created with a different key: replace it.
      const stale = await registration.pushManager.getSubscription();
      await stale?.unsubscribe();
      return { state: "granted-unsubscribed", retry: true };
    }
    throw err; // AbortError: push service or network failure; show a retry option
  }
  await saveOnServer(subscription);
  return { state: "subscribed" };
}

export async function disablePush() {
  const subscription = await registration?.pushManager.getSubscription();
  if (!subscription) return { state: "granted-unsubscribed" };
  // Tell the server first so it stops sending even if unsubscribe() fails.
  await deleteOnServer(subscription.endpoint).catch(() => {});
  const removed = await subscription.unsubscribe(); // false if already deactivated
  return { state: "granted-unsubscribed", removed };
}

async function fetchVapidKey() {
  const res = await fetch(API.publicKey, { headers: { Accept: "application/json" } });
  if (!res.ok) throw new Error(`VAPID key request failed: ${res.status}`);
  const { keyId, publicKey } = await res.json(); // base64url, 65 bytes decoded
  return { id: keyId, bytes: base64UrlToBytes(publicKey) };
}

async function saveOnServer(subscription) {
  const res = await fetch(API.subscriptions, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    credentials: "same-origin",
    body: JSON.stringify({ keyId: vapidKey.id, subscription: subscription.toJSON() }),
  });
  if (!res.ok) throw new Error(`Saving subscription failed: ${res.status}`);
}

async function deleteOnServer(endpoint) {
  const res = await fetch(API.subscriptions, {
    method: "DELETE",
    headers: { "Content-Type": "application/json" },
    credentials: "same-origin",
    keepalive: true, // survives an immediate navigation or tab close
    body: JSON.stringify({ endpoint }),
  });
  if (!res.ok && res.status !== 404) throw new Error(`Delete failed: ${res.status}`);
}

function base64UrlToBytes(value) {
  const padded = value + "=".repeat((4 - (value.length % 4)) % 4);
  const binary = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
  return Uint8Array.from(binary, (c) => c.charCodeAt(0));
}

function sameBytes(buffer, bytes) {
  if (!buffer) return false;
  const a = new Uint8Array(buffer);
  return a.length === bytes.length && a.every((v, i) => v === bytes[i]);
}

Wire it to your UI so that the button handler calls enablePush() directly:

import { initPush, enablePush, disablePush } from "./push-client.js";

const button = document.querySelector("#notify-toggle");
const status = document.querySelector("#notify-status");

function render({ state, reason }) {
  button.hidden = state === "unsupported" || state === "blocked";
  button.textContent = state === "subscribed" ? "Turn off notifications" : "Turn on notifications";
  status.textContent = {
    unsupported: reason === "ios-needs-home-screen"
      ? "Add this app to your Home Screen to enable notifications."
      : "Notifications are not available in this browser.",
    blocked: "Notifications are blocked. Re-enable them in your browser's site settings.",
    prompt: "",
    "granted-unsubscribed": "",
    subscribed: "You will be notified about replies and mentions.",
  }[state];
}

let current = await initPush().catch(() => ({ state: "unsupported" }));
render(current);

button.addEventListener("click", async () => {
  button.disabled = true;
  try {
    current = current.state === "subscribed" ? await disablePush() : await enablePush();
  } catch (err) {
    console.error(err);
    status.textContent = "Something went wrong. Please try again.";
  } finally {
    button.disabled = false;
    render(current);
  }
});

The PushSubscription object¶

A PushSubscription is everything your server needs to reach one browser profile on one origin:

[Exposed=(Window,Worker), SecureContext]
interface PushSubscription {
  readonly attribute USVString endpoint;
  readonly attribute EpochTimeStamp? expirationTime;
  [SameObject] readonly attribute PushSubscriptionOptions options;
  ArrayBuffer? getKey(PushEncryptionKeyName name);   // "p256dh" | "auth"
  Promise<boolean> unsubscribe();
  PushSubscriptionJSON toJSON();
};

JSON.stringify(subscription) calls toJSON() for you. A typical serialized subscription looks like this (values shortened):

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/dJ1u0...:APA91bE...",
  "expirationTime": null,
  "keys": {
    "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM",
    "auth": "tBHItJI5svbpez7KI4CCXg"
  }
}

The endpoint is a bearer capability for delivery, protected by VAPID, and the keys are what makes a payload decryptable. Anyone who holds all three values and your VAPID private key can message that user. Store subscriptions like credentials: encrypted at rest if your policy requires it, never in client-side analytics, and never in logs.

expirationTime deserves a note. The spec lets a push service set an expiry and says the browser should refresh the subscription before it expires and fire pushsubscriptionchange. In practice you cannot rely on either: most subscriptions report null, and subscriptions also die without warning (the user clears site data, revokes permission, or the push service expires the endpoint). Your server learns about those only from a 404 or 410 on the next send. Store expirationTime when it is present and treat it as a hint.

Storing subscriptions on the server¶

One user has many subscriptions (phone, laptop, work profile), and one subscription can move between users on a shared device. Model it that way:

CREATE TABLE push_subscriptions (
  id               bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  user_id          bigint      NOT NULL REFERENCES users (id) ON DELETE CASCADE,
  endpoint         text        NOT NULL UNIQUE,   -- full URL, exactly as received
  p256dh           text        NOT NULL,          -- base64url, 65 bytes decoded
  auth             text        NOT NULL,          -- base64url, 16 bytes decoded
  expiration_time  timestamptz,                   -- usually NULL
  vapid_key_id     text        NOT NULL,          -- which key pair it was created with
  push_service     text        NOT NULL,          -- endpoint host, for metrics and throttling
  user_agent       text,
  created_at       timestamptz NOT NULL DEFAULT now(),
  last_seen_at     timestamptz NOT NULL DEFAULT now(), -- last re-sync from a page load
  last_success_at  timestamptz,                   -- last 201 from the push service
  failure_count    integer     NOT NULL DEFAULT 0
);
CREATE INDEX push_subscriptions_user_id_idx ON push_subscriptions (user_id);

Design notes that matter in production:

• Upsert on endpoint. The page re-sends the subscription on every load, and the same endpoint may arrive under a different user after a logout and login on a shared device. ON CONFLICT (endpoint) DO UPDATE handles both and keeps one row per browser.
• Validate before storing. Parse the endpoint as a URL, require https:, and check the host against the push services you support. Without that allowlist, anyone can make your sender POST to an arbitrary URL, which is a server-side request forgery vector. Also check that p256dh decodes to 65 bytes starting with 0x04 and auth to 16 bytes, so malformed rows fail at write time rather than at send time.
• Authenticate and protect against CSRF. The subscription endpoints change who receives a user's notifications. Require a session and use your normal CSRF defenses.
• Keep last_seen_at and last_success_at. A subscription that has not been re-synced for months and whose sends keep failing is a candidate for pruning even if the push service never returned 410.
• Handle logout explicitly. Either unsubscribe the browser (the user stops receiving anything) or detach the row from the user (DELETE it) so the next person on the device does not get the previous user's messages.

The routes below implement this for Express 5 and PostgreSQL:

import express from "express";
import { pool } from "./db.js";

export const pushRouter = express.Router();

// Push services you are willing to call. Anything else is rejected to prevent
// your sender from being used for server-side request forgery (SSRF).
const PUSH_HOST_SUFFIXES = [
  "fcm.googleapis.com", // Chrome and most Chromium browsers
  "push.services.mozilla.com", // Firefox (updates.push.services.mozilla.com)
  "push.apple.com", // Safari and iOS/iPadOS Home Screen web apps
  "notify.windows.com", // Microsoft Edge on Windows (WNS)
];
const B64URL = /^[A-Za-z0-9_-]+$/;

function parseSubscription(input) {
  if (!input || typeof input.endpoint !== "string" || input.endpoint.length > 2048) {
    throw new TypeError("endpoint missing or too long");
  }
  const url = new URL(input.endpoint);
  const hostOk = PUSH_HOST_SUFFIXES.some(
    (suffix) => url.hostname === suffix || url.hostname.endsWith(`.${suffix}`),
  );
  if (url.protocol !== "https:" || !hostOk) throw new TypeError("unknown push service");

  const { p256dh, auth } = input.keys ?? {};
  if (!B64URL.test(p256dh ?? "") || !B64URL.test(auth ?? "")) throw new TypeError("bad keys");
  const pub = Buffer.from(p256dh, "base64url");
  const secret = Buffer.from(auth, "base64url");
  // RFC 8291: uncompressed P-256 point (65 bytes, 0x04 prefix) and a 16-byte auth secret.
  if (pub.length !== 65 || pub[0] !== 0x04 || secret.length !== 16) {
    throw new TypeError("keys have the wrong length");
  }
  const expirationTime =
    typeof input.expirationTime === "number" ? new Date(input.expirationTime) : null;
  return { endpoint: url.href, p256dh, auth, expirationTime, service: url.hostname };
}

// Public key for the browser. keyId lets you rotate keys without guessing.
pushRouter.get("/api/push/vapid-public-key", (req, res) => {
  res.set("Cache-Control", "public, max-age=3600");
  res.json({ keyId: process.env.VAPID_KEY_ID, publicKey: process.env.VAPID_PUBLIC_KEY });
});

pushRouter.post("/api/push/subscriptions", express.json({ limit: "8kb" }), async (req, res) => {
  if (!req.user) return res.sendStatus(401); // your session middleware sets req.user
  let sub;
  try {
    sub = parseSubscription(req.body?.subscription);
  } catch (err) {
    return res.status(400).json({ error: err.message });
  }
  // Upsert by endpoint: the same browser re-sends on every page load, and a
  // shared device may move the endpoint to a different signed-in user.
  await pool.query(
    `INSERT INTO push_subscriptions
       (user_id, endpoint, p256dh, auth, expiration_time, vapid_key_id, push_service, user_agent)
     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
     ON CONFLICT (endpoint) DO UPDATE SET
       user_id = EXCLUDED.user_id,
       p256dh = EXCLUDED.p256dh,
       auth = EXCLUDED.auth,
       expiration_time = EXCLUDED.expiration_time,
       vapid_key_id = EXCLUDED.vapid_key_id,
       user_agent = EXCLUDED.user_agent,
       last_seen_at = now(),
       failure_count = 0`,
    [
      req.user.id,
      sub.endpoint,
      sub.p256dh,
      sub.auth,
      sub.expirationTime,
      String(req.body.keyId ?? process.env.VAPID_KEY_ID),
      sub.service,
      req.get("user-agent")?.slice(0, 512) ?? null,
    ],
  );
  res.sendStatus(204);
});

// Called by the service worker's pushsubscriptionchange handler. It may run
// without a page, so it authenticates with the session cookie like any fetch.
pushRouter.post("/api/push/subscriptions/replace", express.json({ limit: "8kb" }), async (req, res) => {
  if (!req.user) return res.sendStatus(401);
  let sub;
  try {
    sub = parseSubscription(req.body?.subscription);
  } catch (err) {
    return res.status(400).json({ error: err.message });
  }
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    // A browser-initiated refresh keeps the old applicationServerKey, so inherit the
    // old row's key ID unless the worker subscribed afresh and told us which key it used.
    let keyId = typeof req.body.keyId === "string" ? req.body.keyId : null;
    if (typeof req.body.oldEndpoint === "string") {
      const { rows } = await client.query(
        "DELETE FROM push_subscriptions WHERE endpoint = $1 AND user_id = $2 RETURNING vapid_key_id",
        [req.body.oldEndpoint, req.user.id],
      );
      keyId ??= rows[0]?.vapid_key_id ?? null;
    }
    await client.query(
      `INSERT INTO push_subscriptions
         (user_id, endpoint, p256dh, auth, expiration_time, vapid_key_id, push_service)
       VALUES ($1, $2, $3, $4, $5, $6, $7)
       ON CONFLICT (endpoint) DO UPDATE SET
         user_id = EXCLUDED.user_id, p256dh = EXCLUDED.p256dh, auth = EXCLUDED.auth,
         vapid_key_id = EXCLUDED.vapid_key_id, last_seen_at = now(), failure_count = 0`,
      [req.user.id, sub.endpoint, sub.p256dh, sub.auth, sub.expirationTime,
       keyId ?? process.env.VAPID_KEY_ID, sub.service],
    );
    await client.query("COMMIT");
    res.sendStatus(204);
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
});

pushRouter.delete("/api/push/subscriptions", express.json({ limit: "8kb" }), async (req, res) => {
  if (!req.user) return res.sendStatus(401);
  const endpoint = req.body?.endpoint;
  if (typeof endpoint !== "string") return res.sendStatus(400);
  const { rowCount } = await pool.query(
    "DELETE FROM push_subscriptions WHERE endpoint = $1 AND user_id = $2",
    [endpoint, req.user.id],
  );
  res.sendStatus(rowCount ? 204 : 404);
});

Sending push messages from your server¶

Anatomy of a push request¶

Every library ultimately sends the same HTTP request to the subscription's endpoint. Seeing it raw makes the library options and the error responses easier to reason about:

POST /fcm/send/dJ1u0...:APA91bE... HTTP/1.1
Host: fcm.googleapis.com
TTL: 3600
Urgency: high
Topic: inbox-count
Content-Type: application/octet-stream
Content-Encoding: aes128gcm
Content-Length: 181
Authorization: vapid t=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOi..., k=BLc4xRzKlKORKWlbdgFaBr...

<binary body: 86-byte aes128gcm header, then ciphertext, then a 16-byte authentication tag>

Three VAPID details cause most 401/403 responses in practice. First, aud must be the origin of the endpoint (https://fcm.googleapis.com, not the full URL and not your own origin), so you need one JWT per push service. Second, exp must be in the future but no more than 24 hours away; servers with a drifting clock produce intermittent failures. Third, Apple's push service rejects some sub values: the web-push documentation notes that a subject of https://localhost fails with a BadJwtToken error. Apple also asks senders not to refresh the JWT more often than once per hour, which is a good reason to cache the signed header per audience, as the senders below do.

Node.js with web-push¶

web-push is the reference Node.js implementation (version 3.6.7 at the time of writing, Node.js 16 or later). Its surface is small:

sendNotification() options and their defaults:

The library signs a new JWT for every call by default, which is wasteful at volume and conflicts with Apple's once-per-hour guidance. The sender below caches one header per push service, validates payload size before encrypting, retries only transient failures, honors Retry-After, deletes subscriptions on 404/410, and bounds concurrency during fan-out:

import webpush from "web-push";
import { pool } from "./db.js";

const { WebPushError } = webpush;

const VAPID = {
  subject: process.env.VAPID_SUBJECT, // "mailto:[email protected]" or an https: URL
  publicKey: process.env.VAPID_PUBLIC_KEY, // base64url, 65 bytes decoded
  privateKey: process.env.VAPID_PRIVATE_KEY, // base64url, 32 bytes decoded
};
const MAX_PLAINTEXT_BYTES = 3993; // 4096-byte body minus aes128gcm overhead (RFC 8291)
const JWT_LIFETIME_S = 12 * 60 * 60; // RFC 8292 caps exp at 24 hours
const JWT_REFRESH_MARGIN_S = 60 * 60;
const CONCURRENCY = 50;
const MAX_ATTEMPTS = 3;

// One signed VAPID header per push-service origin, reused until close to expiry.
// Apple asks senders not to refresh the JWT more often than once per hour.
const vapidHeaderCache = new Map();

function vapidAuthorization(endpoint) {
  const audience = new URL(endpoint).origin;
  const now = Math.floor(Date.now() / 1000);
  const cached = vapidHeaderCache.get(audience);
  if (cached && cached.exp - JWT_REFRESH_MARGIN_S > now) return cached.header;
  const exp = now + JWT_LIFETIME_S;
  const { Authorization } = webpush.getVapidHeaders(
    audience, VAPID.subject, VAPID.publicKey, VAPID.privateKey, "aes128gcm", exp,
  );
  vapidHeaderCache.set(audience, { header: Authorization, exp });
  return Authorization;
}

/**
 * Send one message to one stored subscription row.
 * @returns {Promise<{ok: boolean, status?: number, retryAfterMs?: number, gone?: boolean, reason?: string}>}
 */
export async function sendToSubscription(row, message, { ttl = 3600, urgency = "normal", topic } = {}) {
  const payload = typeof message === "string" ? message : JSON.stringify(message);
  const bytes = Buffer.byteLength(payload, "utf8");
  if (bytes > MAX_PLAINTEXT_BYTES) {
    throw new RangeError(`push payload is ${bytes} bytes, limit ${MAX_PLAINTEXT_BYTES}`);
  }
  const subscription = { endpoint: row.endpoint, keys: { p256dh: row.p256dh, auth: row.auth } };

  for (let attempt = 1; ; attempt++) {
    try {
      const res = await webpush.sendNotification(subscription, payload, {
        TTL: ttl,
        urgency,
        topic, // undefined is ignored; max 32 base64url characters
        vapidDetails: null, // skip per-request signing: we pass a cached header
        headers: { Authorization: vapidAuthorization(row.endpoint) },
        timeout: 10_000,
      });
      await pool.query(
        "UPDATE push_subscriptions SET last_success_at = now(), failure_count = 0 WHERE id = $1",
        [row.id],
      );
      return { ok: true, status: res.statusCode };
    } catch (err) {
      const outcome = await classify(row, err);
      if (!outcome.retry || attempt >= MAX_ATTEMPTS) return outcome;
      const backoff = outcome.retryAfterMs ?? 1000 * 2 ** attempt + Math.random() * 1000;
      await new Promise((resolve) => setTimeout(resolve, Math.min(backoff, 60_000)));
    }
  }
}

async function classify(row, err) {
  if (!(err instanceof WebPushError)) {
    // DNS failure, TLS error, socket timeout: transient.
    return { ok: false, retry: true, reason: err.code ?? err.message };
  }
  const status = err.statusCode;
  if (status === 404 || status === 410) {
    // Expired or unsubscribed. Never send to this endpoint again.
    await pool.query("DELETE FROM push_subscriptions WHERE id = $1", [row.id]);
    return { ok: false, retry: false, gone: true, status };
  }
  if (status === 429 || status >= 500) {
    return { ok: false, retry: true, status, retryAfterMs: parseRetryAfter(err.headers?.["retry-after"]) };
  }
  if (status === 401 || status === 403) {
    // Bad or expired JWT, clock skew, or the subscription was created with a
    // different applicationServerKey. Drop the cached header and record it.
    vapidHeaderCache.delete(new URL(row.endpoint).origin);
  }
  // 400, 401, 403, 413 and anything else: our request is wrong; retrying will not help.
  await pool.query(
    "UPDATE push_subscriptions SET failure_count = failure_count + 1 WHERE id = $1",
    [row.id],
  );
  return { ok: false, retry: false, status, reason: String(err.body).slice(0, 500) };
}

function parseRetryAfter(value) {
  if (!value) return undefined;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return seconds * 1000;
  const date = Date.parse(value); // HTTP-date form
  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
}

/** Fan out one message to every device of a user, with bounded concurrency. */
export async function sendToUser(userId, message, options) {
  const { rows } = await pool.query(
    "SELECT id, endpoint, p256dh, auth FROM push_subscriptions WHERE user_id = $1",
    [userId],
  );
  const results = [];
  const queue = [...rows];
  const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
    for (let row = queue.shift(); row; row = queue.shift()) {
      results.push({ id: row.id, ...(await sendToSubscription(row, message, options)) });
    }
  });
  await Promise.all(workers);
  return results;
}

Calling it from application code looks like this. The payload uses the Declarative Web Push format, which the service worker below understands in every browser:

import { sendToUser } from "./push-sender.js";

export async function notifyReply({ recipientId, thread, reply }) {
  const results = await sendToUser(
    recipientId,
    {
      web_push: 8030,
      notification: {
        title: `${reply.authorName} replied`,
        body: reply.excerpt.slice(0, 140),
        navigate: `https://app.example.com/threads/${thread.id}#reply-${reply.id}`,
        tag: `thread-${thread.id}`, // one notification per thread on the device
        data: { threadId: thread.id, replyId: reply.id },
      },
    },
    { ttl: 24 * 60 * 60, urgency: "normal", topic: `thread-${thread.id}` },
  );
  const delivered = results.filter((r) => r.ok).length;
  const pruned = results.filter((r) => r.gone).length;
  console.info({ recipientId, delivered, pruned, total: results.length });
}

For large audiences, do not fan out inside a web request. Put one job per recipient (or per subscription) on a queue, let workers call sendToSubscription(), and keep separate rate limits per push service so that a 429 from one service does not stall delivery to the others. Reuse connections: pass a keep-alive https.Agent through the agent option, or send the output of generateRequestDetails() through an HTTP/2 client. Apple's documentation allows HTTP/1.1 and HTTP/2, asks you not to exceed 100 unacknowledged pipelined requests on an HTTP/1.1 connection, and asks you to respect the server's SETTINGS_MAX_CONCURRENT_STREAMS on HTTP/2.

Python with pywebpush¶

pywebpush (2.5.0 in August 2026, Python 3.10 or later) offers a one-call webpush() function, a WebPusher class for repeated sends, and webpush_async() built on aiohttp. Two of its defaults need attention:

• ttl defaults to 0. A message sent without an explicit TTL is dropped by the push service if the device is not connected at that instant. Always pass ttl.
• vapid_claims is mutated. If the dict has no aud, webpush() fills it in from the first endpoint it sees and, if exp is missing or past, sets it to 12 hours ahead. Reusing one module-level claims dict therefore sends the FCM audience to Mozilla or Apple on later calls, which fails with 401/403. Build a fresh dict per call, or sign the header yourself as below.

WebPushException carries the underlying requests response in .response (current releases also expose .status_code and .retry_after shortcuts). This sender mirrors the Node.js version, including per-audience header caching through py_vapid, which pywebpush depends on:

"""push_sender.py: send web push messages with pywebpush and prune dead subscriptions."""

from __future__ import annotations

import json
import os
import random
import time
from dataclasses import dataclass
from email.utils import parsedate_to_datetime
from urllib.parse import urlsplit

import psycopg
import requests
from psycopg.rows import dict_row
from py_vapid import Vapid
from pywebpush import WebPushException, webpush

VAPID_SUBJECT = os.environ["VAPID_SUBJECT"]  # "mailto:[email protected]"
VAPID_PRIVATE_KEY = os.environ["VAPID_PRIVATE_KEY"]  # raw base64url (web-push format) or DER
MAX_PLAINTEXT_BYTES = 3993
JWT_LIFETIME_S = 12 * 60 * 60
JWT_REFRESH_MARGIN_S = 60 * 60
MAX_ATTEMPTS = 3

_vapid = Vapid.from_string(VAPID_PRIVATE_KEY)
_header_cache: dict[str, tuple[str, int]] = {}  # audience -> (Authorization, exp)
_session = requests.Session()  # connection reuse matters when fanning out


@dataclass
class SendResult:
    ok: bool
    status: int | None = None
    gone: bool = False
    retry_after: float | None = None
    reason: str | None = None


def _authorization(endpoint: str) -> str:
    parts = urlsplit(endpoint)
    audience = f"{parts.scheme}://{parts.netloc}"
    now = int(time.time())
    cached = _header_cache.get(audience)
    if cached and cached[1] - JWT_REFRESH_MARGIN_S > now:
        return cached[0]
    exp = now + JWT_LIFETIME_S
    # Build a fresh claims dict every time: pywebpush's webpush() mutates the
    # dict you pass (it fills in "aud"), which breaks reuse across push services.
    header = _vapid.sign({"sub": VAPID_SUBJECT, "aud": audience, "exp": exp})["Authorization"]
    _header_cache[audience] = (header, exp)
    return header


def _retry_after_seconds(value: str | None) -> float | None:
    if not value:
        return None
    try:
        return float(value)
    except ValueError:
        try:
            return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
        except (TypeError, ValueError):
            return None


def send_to_subscription(
    conn: psycopg.Connection,
    row: dict,
    message: dict | str,
    *,
    ttl: int = 3600,
    urgency: str = "normal",
    topic: str | None = None,
) -> SendResult:
    payload = message if isinstance(message, str) else json.dumps(message, separators=(",", ":"))
    size = len(payload.encode("utf-8"))
    if size > MAX_PLAINTEXT_BYTES:
        raise ValueError(f"push payload is {size} bytes, limit {MAX_PLAINTEXT_BYTES}")

    subscription_info = {
        "endpoint": row["endpoint"],
        "keys": {"p256dh": row["p256dh"], "auth": row["auth"]},
    }
    headers = {"Urgency": urgency}
    if topic:
        headers["Topic"] = topic  # at most 32 base64url characters

    for attempt in range(1, MAX_ATTEMPTS + 1):
        headers["Authorization"] = _authorization(row["endpoint"])
        try:
            response = webpush(
                subscription_info,
                data=payload,
                headers=headers,
                ttl=ttl,  # pywebpush defaults to 0: always pass it explicitly
                timeout=10,
                requests_session=_session,
            )
            conn.execute(
                "UPDATE push_subscriptions SET last_success_at = now(), failure_count = 0 WHERE id = %s",
                (row["id"],),
            )
            return SendResult(ok=True, status=response.status_code)
        except WebPushException as exc:
            status = exc.response.status_code if exc.response is not None else None
            if status in (404, 410):
                conn.execute("DELETE FROM push_subscriptions WHERE id = %s", (row["id"],))
                return SendResult(ok=False, status=status, gone=True)
            if status is None or status == 429 or status >= 500:
                wait = _retry_after_seconds(
                    exc.response.headers.get("Retry-After") if exc.response is not None else None
                )
                if attempt == MAX_ATTEMPTS:
                    return SendResult(ok=False, status=status, retry_after=wait, reason=exc.message)
                time.sleep(min(wait if wait is not None else 2**attempt + random.random(), 60))
                continue
            if status in (401, 403):
                parts = urlsplit(row["endpoint"])
                _header_cache.pop(f"{parts.scheme}://{parts.netloc}", None)
            conn.execute(
                "UPDATE push_subscriptions SET failure_count = failure_count + 1 WHERE id = %s",
                (row["id"],),
            )
            body = exc.response.text[:500] if exc.response is not None else ""
            return SendResult(ok=False, status=status, reason=body)
        except requests.RequestException as exc:  # DNS, TLS, timeout
            if attempt == MAX_ATTEMPTS:
                return SendResult(ok=False, reason=str(exc))
            time.sleep(2**attempt + random.random())
    return SendResult(ok=False, reason="unreachable")


def send_to_user(conn: psycopg.Connection, user_id: int, message: dict, **options) -> list[SendResult]:
    with conn.cursor(row_factory=dict_row) as cur:
        cur.execute(
            "SELECT id, endpoint, p256dh, auth FROM push_subscriptions WHERE user_id = %s",
            (user_id,),
        )
        rows = cur.fetchall()
    return [send_to_subscription(conn, row, message, **options) for row in rows]

py_vapid's Vapid.from_string() accepts either a raw 32-byte key in base64url (the format web-push generates) or a DER-encoded key, so both stacks can share one key pair.

Quick one-off sends for testing¶

When you only need to fire a message at one subscription, for example while developing the service worker:

npx web-push send-notification \
  --endpoint="https://fcm.googleapis.com/fcm/send/dJ1u0..." \
  --key="BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4..." \
  --auth="tBHItJI5svbpez7KI4CCXg" \
  --payload='{"title":"Test","body":"Hello from the CLI","url":"/inbox"}' \
  --ttl=60 \
  --vapid-subject="mailto:[email protected]" \
  --vapid-pubkey="$VAPID_PUBLIC_KEY" \
  --vapid-pvtkey="$VAPID_PRIVATE_KEY"

import webpush from "web-push";
import { readFile } from "node:fs/promises";

const subscription = JSON.parse(await readFile("subscription.json", "utf8"));
webpush.setVapidDetails(
  "mailto:[email protected]",
  process.env.VAPID_PUBLIC_KEY,
  process.env.VAPID_PRIVATE_KEY,
);
try {
  const res = await webpush.sendNotification(
    subscription,
    JSON.stringify({ title: "Test", body: "Hello from Node.js", url: "/inbox" }),
    { TTL: 60, urgency: "high" },
  );
  console.log(res.statusCode); // 201
} catch (err) {
  console.error(err.statusCode, err.body); // WebPushError
}

import json
import os

from pywebpush import WebPushException, webpush

with open("subscription.json") as f:
    subscription = json.load(f)

try:
    response = webpush(
        subscription,
        data=json.dumps({"title": "Test", "body": "Hello from Python", "url": "/inbox"}),
        vapid_private_key=os.environ["VAPID_PRIVATE_KEY"],
        vapid_claims={"sub": "mailto:[email protected]"},  # fresh dict per call
        ttl=60,
        headers={"Urgency": "high"},
    )
    print(response.status_code)  # 201
except WebPushException as exc:
    print(exc.response.status_code if exc.response is not None else None, exc)