A subscription is a changing browser record
It is not a permanent person identifier. Store the endpoint and encryption keys as sensitive data, associate the record with the correct site and optional account, upsert it idempotently, and retire it when browser or protocol evidence requires it.
Model a subscription as one browser context
A subscription belongs to a service-worker registration and contains a unique push endpoint plus key material. The same person can have separate subscriptions on a laptop, phone, work profile, private browser profile, or installed web app. Conversely, a shared browser may not represent one durable person. Keep account identity, browser subscription, and marketing preference as separate records joined through explicit relationships.
Store enough state to operate and audit safely
| Field | Reason |
|---|---|
| Site or tenant ID | Prevents an endpoint from crossing origin or customer boundaries. |
Endpoint, p256dh, and auth | Required to address and encrypt a message for this subscription. |
| VAPID key version | Selects the application-server identity associated with the population; keep it aligned with the VAPID key-rotation plan. |
| Created, confirmed, and last-success timestamps | Separates record age from recent evidence that the endpoint still accepts sends. |
| Status and failure reason | Supports active, unsubscribed, expired, invalid, and suppressed states without erasing history prematurely. |
| Preference source and topics | Records what the person requested instead of inferring consent from endpoint existence. |
Encrypt sensitive fields at rest where appropriate, restrict who and what can read them, and redact complete endpoints and authentication secrets from ordinary logs.
Make subscription writes idempotent
When the browser returns a subscription, send the complete serialized record to the application server over authenticated HTTPS. Validate the expected object shape, endpoint scheme, key lengths, and site association. Use a unique constraint or deterministic lookup so repeated registration calls update the same current record instead of creating duplicates.
Do not deduplicate only by account. One account may legitimately have several devices. A practical uniqueness boundary is the tenant plus exact endpoint, with additional bookkeeping for account, anonymous session, or browser installation as your product requires.
Reconcile the browser and server views
On a relevant settings page or after sign-in, ask the ready registration for getSubscription(). If a browser subscription exists, upsert it and update the last-confirmed time. If it does not exist, do not silently create one unless the person has already granted permission and your interface makes the action clear. A stale server record cannot prove a current browser subscription.
If an account is used across devices, show each subscribed browser as a separate destination when possible. “Unsubscribe this browser” should call subscription.unsubscribe() and update that endpoint’s server state. “Turn off all notifications” is a broader preference action and may need to suppress every related record.
Retire endpoints from protocol evidence
Push services can return permanent responses when a subscription is no longer valid. Mark those records inactive and stop retrying them. Keep enough event history to explain aggregate counts, but exclude the sensitive endpoint from active sends. Transient server errors and rate limits are different: use the Web Push status-code decision table to separate bounded retries from permanent retirement.
A successful push-service response is useful fresh evidence, but it still does not prove that the device displayed or the person saw the notification. Name the timestamp accordingly, such as last_accepted_at, rather than last_delivered_at.
Handle permission changes and cleared storage
Give people the layered controls in the unsubscribe and preference-center blueprint. If records move between vendors, use the provider migration control plan instead of marking an unverified export active.
A person can revoke notification permission or clear site data outside your interface. The server may learn only when a later send fails or when the site is opened again. Design cleanup as normal lifecycle maintenance, and keep it distinct from the permission-request experience. The permission and subscriber-trust guide path connects this lifecycle evidence to prompt, preference, and frequency decisions. Avoid accusing the person of “unsubscribing” when the only evidence is endpoint invalidation; browsers can rotate or discard records for several reasons.
Use a lifecycle state machine
- Pending: the client is creating and sending the record.
- Active: the server validated and stored the subscription under a current preference.
- Suppressed: the endpoint remains known but policy blocks sends, such as a paused topic or account-level opt-out.
- Unsubscribed: the client explicitly removed the browser subscription or the person disabled it in your interface.
- Invalid: protocol evidence says the endpoint can no longer receive sends.
Record the transition reason and time. This makes support, privacy requests, and reporting more accurate than one is_active boolean.
Use the browser subscription as the source of delivery coordinates
The service's subscription workflow stores this browser-issued record inside an origin-specific product boundary; it does not turn an endpoint into a portable contact address.
The W3C Push API defines the PushSubscription, endpoint, keys, and unsubscribe behavior. RFC 8030 defines the HTTP delivery protocol and expired-subscription behavior. For why the key material must travel through a protected channel, see RFC 8291.