Origin
HTTPS is enforced, the service-worker scope is intentional, and the registered origin must pass file-based ownership verification before subscriptions are accepted.
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.
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.
if ('serviceWorker' in navigator && 'PushManager' in window) {
const registration = await navigator.serviceWorker.register('/push-sw.js');
const subscription = await registration.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey
});
}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().
self.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.
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.
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.
POST /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"
}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.
{
"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.
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.
Site: 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.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.
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.
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.
HTTPS is enforced, the service-worker scope is intentional, and the registered origin must pass file-based ownership verification before subscriptions are accepted.
Private VAPID keys and API tokens are server-only, rotated deliberately, and excluded from URLs and browser bundles.
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.
Campaign state, accepted attempts, provider failures, usage totals, and manual opt-outs can be reviewed without displaying confidential endpoint data.
Short answers to the implementation boundaries most likely to change an integration plan.
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.
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.
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.