Preserve the browser contract before changing the vendor contract
A Web Push provider migration can preserve subscribers only when the new system can use the existing origin, service-worker relationship, subscription data, encryption material, and compatible VAPID credentials. A database export alone does not make subscriptions portable.
Inventory those invariants first. If a vendor owns a required key or never exports complete subscription records, plan a transparent resubscription path instead of promising a silent transfer.
Classify what the current provider actually controls
| Asset | Migration question | Consequence if unavailable |
|---|---|---|
| Website origin | Do you continue to control the same HTTPS origin? | A different origin cannot simply assume the old origin's browser permission or worker registration. |
| Service worker | Is the file on your origin, and can you change it without removing unrelated handlers? | A vendor-only worker path may require a staged takeover and careful scope testing. |
| Subscription records | Can you export each endpoint, p256dh key, auth secret, and necessary site association? | Incomplete records cannot construct valid encrypted sends. |
| Application server key | Were subscriptions created with a VAPID public key whose private key you control? | Subscriptions restricted to the old key may require resubscription if the matching private key cannot move. |
| Consent and preferences | Can you export topics, pauses, source, dates, and opt-outs with their meaning intact? | Moving endpoints without subscriber choices creates trust and compliance risk. |
| Event history | Can you retain bounded attempt, failure, click, and suppression evidence? | Cutover results cannot be compared or explained reliably. |
Choose one of three honest migration paths
Direct send-system migration
Use this path when you control the same origin, compatible worker, complete subscription records, and the VAPID private key associated with current subscriptions. Import records into a quarantined state, validate their shape and ownership, then test a small opted-in cohort before expanding.
Worker takeover with the same subscription contract
Use this when the provider supplied the worker code but you can preserve its scope and required event behavior. Merge existing fetch, push, notification-click, and update logic deliberately. Do not overwrite the file with a minimal new worker and assume browsers will activate it safely.
Explicit resubscription
Use this when critical keys or record fields cannot move. Explain that notification delivery needs to be re-enabled, trigger the flow from a meaningful user action, and keep the site usable when the person declines. Browser permission may remain granted while the old subscription is unusable, so the interface must check both states.
Build a reconciliation file before importing anything
Create one row per source record with the source site ID, destination site ID, consent category, preference state, created time, last useful activity, endpoint fingerprint, key presence, VAPID-key family, and planned action. Never use a raw endpoint as a spreadsheet identifier. Encrypt the transfer and restrict it to the migration team because endpoints and subscription keys are sensitive delivery credentials.
- Reject rows without a verified source origin or destination account.
- Keep opt-outs and pauses excluded; do not treat them as inactive data to reactivate.
- Deduplicate by an endpoint fingerprint inside the correct site boundary.
- Quarantine records with missing key material or an unknown VAPID relationship.
- Assign a migration batch and source record ID for rollback and support.
The subscription lifecycle state model provides safer states than importing every record directly as active.
Run a shadow comparison without double-sending
Map every source capability to what the web push notification service currently supports before deciding that a feature, preference, or delivery state can transfer.
A useful shadow stage validates destination selection, payload construction, expiry policy, and provider routing in the new system without sending a second user-visible notification. Compare intended audience counts and suppression reasons. Where the infrastructure permits a real delivery test, use an internal device cohort with distinct test content.
- Freeze changes to credential ownership and document the source configuration.
- Import one bounded batch in a non-sending or quarantined state.
- Compare eligibility results between old and new systems using the same campaign definition.
- Send internal test messages across the supported device matrix.
- Enable a small production cohort exactly once, with an idempotency key shared across cutover controls.
- Compare provider acceptance, permanent failures, clicks, opt-outs, queue delay, and support reports.
- Expand only after the predefined stop conditions remain clear.
Define stop conditions and rollback in advance
Pause the cutover for a material authentication-error spike, duplicate sends, wrong destinations, unexpected opt-outs, missing preference enforcement, worker activation failure, or permanent-failure rates outside the documented baseline. Rollback should switch the sending authority, not restore an old worker blindly or recreate deleted subscriptions.
Keep one system authoritative for each subscription and campaign. If both systems can send, a rollback flag must also prevent the other queue from releasing the same notification intent.
Handle VAPID changes as a subscription decision
VAPID identifies the application server to the push service, and a subscription can be restricted to an application server key. If the original private key is exportable and permitted to move, protect it as a production secret and verify the audience and authorization behavior in the new sender. If it cannot move, do not manufacture a new private key and expect old restricted subscriptions to accept it. Follow the VAPID key and rotation guide and test the actual subscription relationship.
Validate the service worker separately from delivery data
Worker rollout has its own failure modes: scope changes, cached script responses, waiting workers, lost event listeners, competing SDKs, and click handlers that open the wrong window. Use the Web Push release checklist on both a previously subscribed browser and a clean browser. A successful endpoint import cannot prove the worker upgrade works.
Close the migration with an evidence ledger
- Preserved
- Count of valid records whose origin, keys, preferences, and active state were verified.
- Repaired
- Records reconciled after a browser visit without changing subscriber intent.
- Resubscription needed
- People shown a truthful enable flow because the prior technical contract could not transfer.
- Retired
- Opted-out, invalid, duplicate, unowned, or permanently rejected records excluded from sending.
Keep the migration date, batches, credential decisions, comparison results, exceptions, and deletion schedule. Remove temporary exports when the rollback window closes.
Primary technical references
The W3C Push API specification defines the relationship among origins, service-worker registrations, application server keys, subscriptions, refresh, and deactivation. RFC 8292 defines VAPID application-server identification and subscription restriction.