Know what encryption protects
RFC 8291 is designed to protect push message content from inspection, modification, and forgery by the push service. The application server encrypts, and the user agent decrypts. The endpoint operator still needs information to route and operate the request, so encryption does not hide every form of metadata. The push service can observe which endpoint receives a request, the time, the encrypted size, and transport-level details.
Notification text is also visible after decryption. Avoid sensitive lock-screen content even though the network payload is encrypted.
Keep three key roles distinct
| Material | Role | Lifecycle |
|---|---|---|
Subscription p256dh public key | Combines with an ephemeral sender private key to derive a shared secret. | Created by the user agent for the subscription and stored with the endpoint. |
Subscription auth secret | Mixed into the key derivation so knowledge of one key alone is insufficient. | Created by the user agent and stored as sensitive subscription data. |
| Application-server ephemeral key and salt | Creates fresh encryption context for a message. | Generated during encryption; the ephemeral private key need not become a long-term secret. |
| VAPID key pair | Identifies and authorizes the application server to the push service. | Long-lived sender identity, managed separately through the VAPID setup and rotation process. |
Use a Web Push library rather than hand-built cryptography
The derivation combines ECDH on P-256, HKDF with SHA-256, the subscription authentication secret, and the encrypted-content-coding process. Correct public-key validation, byte encoding, padding, headers, and record rules matter. Use a maintained library with test vectors and configure it with the exact subscription object. Custom cryptography creates failure and security risk without adding product value.
Plan against the protocol payload budget
RFC 8291 notes that a push service is not required to support more than 4,096 octets in the payload body. Encryption framing consumes part of that amount; the RFC calculates a maximum of 3,993 octets of plaintext under its stated minimum-overhead assumptions. Treat that as a protocol ceiling, not a recommended content target. Libraries and services may impose other practical constraints, and multibyte characters consume more than one byte.
A compact payload should identify the notification and include only presentation fields and an approved destination or server-side lookup identifier. Do not embed a complete article, account record, or large image. Notification images and icons are referenced by URL when supported; their binaries do not belong in the push payload. Use the notification preview tool to check the visible message without turning the payload into a document.
Measure bytes after serialization
const payload = JSON.stringify(message);
const plaintextBytes = new TextEncoder().encode(payload).byteLength;
if (plaintextBytes > SAFE_APPLICATION_BUDGET) {
throw new Error("Push payload exceeds the application budget");
}
Choose an application budget below the protocol maximum and enforce it before queueing. Count the serialized UTF-8 bytes, not JavaScript string length. Keep spare room for schema changes and fields inserted by the send library.
Use a versioned, minimal schema
{
"v": 1,
"title": "Order shipped",
"body": "Order 1842 is on the way.",
"url": "/orders/1842",
"tag": "order-1842"
}
Versioning lets older workers reject or safely fall back when they receive a newer shape during deployment. Validate every field in the worker. Keep URLs relative or enforce an allowlisted origin so payload data cannot create an open redirect. A tag can help replace related notifications on platforms that support the behavior, but it should not become the only campaign identifier in analytics.
Do not log the plaintext by default
Delivery troubleshooting needs message IDs, campaign IDs, endpoint record IDs, byte counts, content schema versions, and push-service responses. It rarely needs complete personalized text or subscription secrets in routine logs. Log a template identifier and bounded diagnostic metadata; use controlled tooling when an authorized investigation genuinely requires content inspection.
Understand failure boundaries
The permission-based browser messaging platform relies on a Web Push library for standards-compliant encryption and keeps private credentials server-side. Use this protocol guide to review that implementation boundary rather than treating the product dashboard as the encryption layer.
- A 413 response can indicate that the request is too large for the push service; classify it with the other Web Push response codes before retrying.
- Decryption failure can result from mismatched or corrupted subscription keys, incorrect encoding, or unsupported content coding.
- A successful service response confirms request acceptance, not successful decryption or user-visible presentation.
- Compressed content is not a workaround; RFC 8291 requires
aes128gcmand warns against encodings that introduce information leakage.
Primary encryption references
RFC 8291, Message Encryption for Web Push, defines the key agreement, authentication secret, derivation, content encoding, and payload-size calculation. RFC 8188 defines encrypted content coding. Use RFC 8292 separately for VAPID sender identification.