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.

What is the Web Push Notification Headers Reference?

Reference for RFC 8030 Web Push request headers — TTL, Urgency, Topic and Content-Encoding — and the RFC 8292 VAPID JWT Authorization scheme used when sending to a push service. It runs free in your browser on Gera Tools, with nothing uploaded.

Web Push Notification Headers Reference

Name: Web Push Notification Headers Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

Header quick-reference

Header	Required	Values / format	Default
`TTL`	Yes	Integer seconds	— (must be set)
`Urgency`	No	`very-low`, `low`, `normal`, `high`	`normal`
`Topic`	No	Short ASCII string, max 32 chars	—
`Content-Encoding`	Yes (if payload)	`aes128gcm`	—
`Content-Type`	Yes (if payload)	`application/octet-stream`	—
`Authorization`	Yes (VAPID)	`vapid t=<JWT>, k=<pubkey>`	—

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.

Understanding TTL and delivery guarantees

The TTL header is the most important control for offline delivery behaviour:

TTL: 0 — deliver immediately or drop. Use for time-sensitive notifications that are useless if delayed (for example, a real-time alert).
TTL: 3600 — retain for up to one hour. The push service retries delivery while the device is offline.
TTL: 86400 — retain for up to one day. Suitable for general notifications like chat messages.

Web Push does not guarantee delivery. A push service may drop a message if the device has been offline longer than TTL, if the subscription has expired, or if the endpoint returns an error. Design your application to tolerate missed notifications — for example by fetching missed items on next app open.

VAPID authorization

VAPID (RFC 8292) identifies your application server to the push service without requiring a pre-registration step per push service. The JWT you send in Authorization must contain:

aud — the push service origin (for example https://fcm.googleapis.com)
exp — expiry timestamp, no more than 24 hours in the future
sub — a contact address: mailto:[email protected] or an https:// URL

The JWT is signed with your ECDSA P-256 private key. The push service verifies it using the public key you send in the k= parameter. Use a web-push library rather than assembling the JWT by hand — getting the key format or signing algorithm wrong results in a 401 with no helpful body.

Tips

TTL is required even for immediate delivery — use TTL: 0 for fire-and-forget.
Set Topic to collapse rapid updates: if a user’s device comes back online after receiving 10 “new message” pushes, they only see the latest one.
VAPID JWT exp must be at most 24 hours in the future; push services reject longer-lived tokens.
Payloads are encrypted end-to-end using keys from the subscription (p256dh and auth); the push service relays ciphertext it cannot read.