Web Push basics: subscriptions, VAPID keys and the push service

What it is

RFC 8030 defines three parties: the browser creates a subscription with a push service chosen by its vendor and receives an endpoint URL; the page sends that subscription, including its encryption keys, to the application server; the server later POSTs a message to the endpoint, and the push service delivers it to the browser, which wakes a service worker's push event. Every delivery request must carry a TTL header (seconds the service may hold the message) and may carry Urgency and Topic (a new message replaces an undelivered one with the same topic). VAPID (RFC 8292) identifies the application server: a JWT signed with an ES256 key (ECDSA on P-256) whose aud claim is the origin of the push endpoint, exp at most 24 hours ahead and optional sub contact URI, sent as Authorization: vapid t=<jwt>, k=<public key>. The same public key is passed to PushManager.subscribe() as applicationServerKey; MDN stresses that this is not the key used to encrypt payloads, and that Chrome and Edge reject subscriptions unless userVisibleOnly is true. Payloads are encrypted end to end (Content-Encoding: aes128gcm), so the push service cannot read them.

Why it matters

Push reaches users while the site is closed, but permission, key handling, encryption and subscription expiry can each fail silently: no error on the page, only messages that never arrive.

How to apply

• Generate one VAPID key pair per application and keep the private key in secrets management; subscriptions are bound to the public key, so rotating it means re-subscribing every user.
• Request notification permission in response to a user action with a stated purpose; an unprompted request on page load is commonly denied, and a denial is hard to reverse.
• Store subscriptions server-side with the user; when the push service answers 404, which RFC 8030 specifies for an expired subscription, delete the record.
• Use a maintained library for the encryption and the JWT; a wrong aes128gcm implementation yields requests the push service accepts but the browser cannot decrypt.
• Set TTL by the message's usefulness window and keep payloads small: services need not accept bodies above 4096 bytes.
• Handle the pushsubscriptionchange event in the service worker to re-subscribe and re-upload the new subscription.

Pitfalls

Confusing the VAPID key with the payload encryption keys. Receiving a push and showing no notification, which contradicts the userVisibleOnly promise made at subscription time. Reading a 201 from the push service as delivery. Treating the endpoint URL as public: without applicationServerKey anyone holding it can post to that browser; with it, RFC 8292 requires the push service to reject requests lacking a token signed by the matching private key, so protect both.