Web push implementation and security

Implementation guides for service workers, VAPID, subscription records, encrypted payloads, endpoint handling, and practical debugging.

OriginWorker registrationBrowser subscriptionVAPID identity

Keep these four objects distinct. Most deployment failures come from mixing their ownership, overwriting an existing worker, exposing a private key, or treating an endpoint as permanent.

Map ownership before writing integration code

ObjectOwnerStorage rule
Service-worker file and scopeThe verified site originServe over HTTPS, version deliberately, and merge with existing worker responsibilities.
VAPID public keyThe sending applicationSafe to provide to subscribing browsers; keep stable for the intended subscription population.
VAPID private keyThe application serverStore only in a secret manager or protected server configuration. Never send it to client JavaScript.
Endpoint, p256dh, and authThe browser subscriptionTreat as sensitive delivery credentials, isolate by tenant and origin, and delete after permanent invalidation.

Complete a launch handoff record

  • Origin and environment: record the exact production origin and keep staging subscriptions, keys, and campaigns separate.
  • Worker URL and scope: record the served URL, effective registration scope, cache headers, update owner, and any existing fetch or background handlers that must survive a change.
  • Sender identity: record the VAPID public-key fingerprint, protected private-key location, contact claim, backup owner, and recovery procedure without copying the private key into the handoff.
  • Subscription storage: document encryption at rest, tenant and origin keys, access roles, retention, idempotency key, and the action taken after permanent invalidation.
  • Release evidence: name the browsers and devices used for permission, foreground, background, closed-state, click, unsubscribe, and worker-update tests.
  • Rollback: identify which worker, API, or campaign change can be reversed independently and who can stop scheduled delivery.

The handoff is useful only when another engineer can reproduce one subscription and one test send without guessing which origin, key population, or worker version is active.

Build one vertical slice before adding campaigns

Start with one HTTPS origin, one known service-worker scope, one visible subscribe button, and one server-side test-send path. Confirm the complete round trip on a real device: registration, permission, subscription storage, encrypted request, push event, notification display, and click navigation. Log identifiers for the site, campaign, send attempt, and endpoint record without logging private keys or raw authentication secrets.

Only after that path is repeatable should you add scheduling, audience queries, retries, templates, or automation. Otherwise each extra layer creates another place for the same basic fault to hide.

Protect the subscription boundary

Accept subscriptions only from an authenticated or otherwise validated site context. Validate the expected endpoint scheme and key fields, cap field sizes, associate the record with the correct site, and make writes idempotent. Do not use an endpoint as a public identifier. An attacker who obtains full subscription material may be able to submit messages if other authorization controls are also compromised.

Boundary checkFailure containedEvidence to retain
Exact origin and tenant associationA browser record being attached to another customer, environment, or sender identity.Internal site identifier, normalized origin, authenticated account identifier, and a bounded rejection reason.
Endpoint and key validationOversized, malformed, non-HTTPS, or incomplete subscription material entering the send queue.Validation result and field lengths, never complete endpoints or authentication secrets in ordinary logs.
Idempotent upsertDuplicate active records inflating audience counts or causing repeated attempts to the same browser subscription.Stable internal record identifier, key version, first-seen time, last-confirmed time, and update result.
Authorized read and deleteSupport tools, exports, or cross-tenant queries exposing delivery credentials.Actor, purpose, affected record count, authorization decision, and deletion or export timestamp.

Subscription data is operational capability material, not a normal mailing-list field. Keep it out of analytics payloads, URLs, screenshots, client error reports, and support tickets.

Plan key and worker changes as migrations

A VAPID private-key loss can make an existing subscription population unusable with the replacement key, depending on how subscriptions were restricted. Keep backups and a rotation plan before launch. A service-worker update can also change notification behavior for every subscriber on an origin. Stage changes, preserve existing event listeners, and verify both newly subscribed and previously subscribed browsers.

Use protocol responses to clean the system

A successful HTTP response means the push service accepted the request under its protocol rules; it does not prove presentation or a click. Permanent invalidation responses should retire the endpoint. Rate limits and transient server failures require bounded backoff. Malformed requests require a code or data fix, not repeated delivery attempts.

Keep the standards boundary visible

RFC 8292 defines VAPID application-server identification. RFC 8291 defines Web Push message encryption. The W3C Push API defines subscription behavior, and the MDN Service Worker API guide is a practical implementation reference.

Choose the component you are building

These are reference chapters rather than a course. Open the component or failure boundary currently in front of you.

  1. Web push service worker implementation guide

    Register the right scope, handle push and notification-click events, preserve existing handlers, and test service-worker updates.

  2. VAPID for Web Push: keys and rotation

    Learn what VAPID identifies, where public and private keys belong, how subscriptions become restricted, and how to rotate safely.

  3. Web push subscription lifecycle

    Store subscription records safely, deduplicate devices, process unsubscribe events, and retire endpoints after permanent failures.

  4. Web push payload encryption and size limits

    Understand aes128gcm encryption, subscription key material, practical payload budgets, and what push services can still observe.

  5. Web push notification testing checklist

    Test Web Push permission, worker updates, subscriptions, offline delivery, notification clicks, failures, and cleanup before release.

  6. Migrate web push providers without losing subscribers

    Plan a Web Push provider migration around origin, service-worker, VAPID, subscription, data-export, cutover, and rollback constraints.

  7. Debug web push notifications step by step

    Trace permission, registration, subscription, server response, push events, notification display, and click handling in order.