What does the TTL header do?

TTL (Time To Live) is a required header giving the number of seconds the push service should retain the message if the device is offline. TTL: 0 means deliver immediately or drop. A larger value lets the push service hold and retry delivery until the device reconnects or the time expires.

What is the Urgency header for?

Urgency tells the push service the message's importance — very-low, low, normal or high. Devices on battery saver may withhold low-urgency messages until a more active period. Setting an appropriate urgency improves battery behaviour and delivery reliability for time-critical alerts.

How does the Topic header work?

Topic is a short string that lets a new message replace a previous undelivered one with the same topic for the same subscription. This collapses a burst of updates into the latest one, so a user coming online does not receive a stale pile of superseded notifications.

What goes in the VAPID Authorization header?

With the vapid scheme the Authorization header carries a signed JWT and your public key: Authorization: vapid t= , k= . The JWT is signed with your private ECDSA P-256 key and includes aud (the push service origin), exp (expiry, max 24h) and sub (a mailto: or https: contact). This identifies your application server to the push service.

How is the payload encrypted?

Payloads use the aes128gcm content coding from RFC 8188, declared with Content-Encoding: aes128gcm. The message is encrypted end-to-end using keys derived from the subscription's p256dh and auth secrets, so the push service relays ciphertext it cannot read. The body is opaque binary with Content-Type: application/octet-stream.

Web Push Notification Headers Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

The Web Push protocol headers

Web Push (RFC 8030) lets an application server deliver a notification to a user agent through an intermediary push service, addressed by the subscription’s endpoint URL. A handful of request headers control retention, priority and de-duplication, and VAPID (RFC 8292) authenticates the sender. This reference covers those headers and the Authorization format.

How it works

The application server sends a POST to the subscription endpoint with an encrypted payload and the control headers; the push service stores or relays it to the device:

POST /push/abc123 HTTP/1.1
Host: push-service.example
TTL: 86400
Urgency: high
Topic: chat-42
Content-Encoding: aes128gcm
Content-Type: application/octet-stream
Authorization: vapid t=<signed-JWT>, k=<base64url-public-key>

<encrypted binary payload>

TTL is mandatory and sets how long the message is retained for an offline device. Urgency and Topic are optional: urgency influences battery-aware delivery, and topic lets a later message replace an undelivered earlier one. The VAPID JWT, signed with your ECDSA P-256 key, proves the sender’s identity.

Tips and notes

TTL is required even for immediate delivery — use TTL: 0 for fire-and-forget.
Set Topic to collapse rapid updates into the latest notification.
VAPID JWT exp must be at most 24 hours in the future or the push service rejects it.
Payloads are encrypted end-to-end; the push service cannot read them.