Web Push API, JavaScript SDK, and service worker documentation

A Web Push integration needs a secure origin, a service worker, a browser subscription created with the site's VAPID public key, and an authenticated server call that sends or stores the campaign.

Browser setup

Web Push requires a secure origin, a service worker, a direct user action before the permission request, and the registered site's VAPID public key. Check feature support before showing a subscribe control.

Use the service-worker implementation guide and VAPID configuration guide for the two server-to-browser trust boundaries.

Browserif ('serviceWorker' in navigator && 'PushManager' in window) { const registration = await navigator.serviceWorker.register('/push-sw.js'); const subscription = await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey }); }

Service worker behavior

The push event is received in the service worker, not in the page. Parse only the expected payload shape, use safe defaults when optional fields are absent, and call showNotification() inside event.waitUntil().

Service workerself.addEventListener('push', event => { const data = event.data ? event.data.json() : {}; event.waitUntil(self.registration.showNotification( data.title || 'New update', { body: data.body || '', data: { url: data.url || '/' } } )); });

On click, validate the destination against an allowed origin, focus an existing matching tab when possible, and otherwise open the campaign destination.

Subscription lifecycle

A subscription has a unique endpoint, encryption keys, an authentication secret, and an association with a service-worker scope. Store the complete subscription record and update it when the browser fires pushsubscriptionchange.

  • Treat 404 and 410 responses as permanent endpoint failures and stop sending.
  • Back off and retry bounded temporary failures such as 429 or 503.
  • Keep unsubscribe available even when the account dashboard is unavailable.
  • Do not transfer subscriptions between registered origins.

REST API boundaries

API tokens are associated with an account. Campaign creation verifies that the selected site belongs to that account, validates bounded strings and a public HTTPS destination, then either stores a draft or queues a future schedule. Read the machine-readable OpenAPI 3.1 schema for current fields and responses.

Campaign requestPOST /api/v1/campaigns Authorization: Bearer <server-token> Content-Type: application/json { "site_id": 42, "title": "Your report is ready", "body": "Open the completed November report.", "target_url": "https://example.com/reports/november", "status": "scheduled", "scheduled_at": "2026-11-18T03:00:00Z" }

MCP server

The stateless MCP endpoint exposes typed tools for listing owned sites, reviewing the delivery overview, reading campaigns, creating drafts, scheduling a future send, and returning a scheduled campaign to drafts. It uses the same bearer token as REST, so integrations never need a browser session or password.

MCP client configuration{ "mcpServers": { "pushnotifications": { "url": "https://pushnotifications.org/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

An MCP tool cannot grant browser permission, change a visitor's subscription choice, bypass account allowances, or force a second attempt within the rolling 24-hour protection window.

Command-line workflow

A command-line client should call the same authenticated REST API as any server integration. Keep the API token in a protected environment variable, pass campaign content through a file or standard input when shell history is a concern, and review the resolved site, audience, destination, and schedule before confirming a send.

Review before sendingSite: example.com Audience: opted-in subscribers Destination: https://example.com/reports/november Schedule: 2026-11-18 03:00 UTC Confirm only after these values match the intended campaign.

Error handling

Return structured errors with a stable code, a safe message, and a request identifier. Never echo authorization headers, push endpoints, encryption keys, model keys, or raw provider responses into logs or client errors. Use the delivery status-code runbook to decide whether to fix, retry, or retire an endpoint.

Security model

Endpoint keys are encrypted at rest, private VAPID keys never reach the browser, and API secrets are accepted only in authorization headers. The current worker enforces account delivery allowances and avoids another attempt to the same subscriber within 24 hours. Review the exact security and ownership-verification boundaries, store browser records using the subscription lifecycle data model, and keep the Web Push debugging checklist beside the production runbook.

Standards references: W3C Push API, MDN Service Worker API, and WebKit Web Push for iOS and iPadOS.

Production readiness checklist

Web Push is a distributed system. Validate the browser path, your application server, vendor push services, and the final destination independently. The implementation and security learning path connects these checks to the detailed worker, VAPID, subscription, encryption, and debugging guides.

Origin

HTTPS is enforced, the service-worker scope is intentional, and the registered origin must pass file-based ownership verification before subscriptions are accepted.

Secrets

Private VAPID keys and API tokens are server-only, rotated deliberately, and excluded from URLs and browser bundles.

Queues

The current worker schedules due campaigns, enforces account allowances, excludes recently contacted subscribers, and removes stale subscriptions after permanent 404 or 410 responses. Temporary failures are recorded without automatic retry.

Observability

Campaign state, accepted attempts, provider failures, usage totals, and manual opt-outs can be reviewed without displaying confidential endpoint data.

Web Push API questions

Short answers to the implementation boundaries most likely to change an integration plan.

Does registering a site prove domain ownership?

Registration starts the ownership check. The account owner must then publish the supplied verification value at the exact well-known HTTPS location before installation can continue.

Can the campaign API schedule a send?

Yes. Create or update an account-owned campaign with a future ISO 8601 scheduled_at value. The same message can be returned to draft before delivery.

Are temporary provider failures retried automatically?

No. The current worker records the failed attempt. Permanent 404 and 410 responses retire the subscription; a bounded temporary-retry policy remains a separate implementation decision.