Email Provider Webhook Event Schema Migration

A provider webhook migration can break suppression, analytics, or retries even while messages continue to send. Treat the webhook as a data contract. Map event meaning, identifiers, timestamps, signatures, retry behavior, and ordering before changing consumers. Use provider documentation and real fixtures; never invent fields.

Inventory the old contract

Capture every event type, required and optional field, identifier semantics, timestamp format, authentication method, retry schedule, and delivery acknowledgment. Trace how each event changes application state. The sending observability guide helps identify the states that must remain observable.

Request or generate sanitized fixtures for accepted, delivered, deferred, bounced, complained, suppressed, and malformed events. Record duplicate and out-of-order behavior. A field named id may identify a message, event, or delivery attempt; confirm its meaning before mapping it.

Build a provider-neutral model

Define a canonical internal event with message ID, recipient or privacy-safe key, provider ID, event type, occurred-at time, received-at time, attempt, source, raw payload reference, and verification status. Preserve raw payloads with access controls. Normalize only what the application truly needs, and retain the provider-specific values for investigation.

Test signature verification, idempotency, replay, dead-letter handling, and retry acknowledgment. Run the new adapter in shadow mode if possible. Compare state transitions between old and new consumers without sending duplicate mail. Use the platform migration runbook for the wider cutover sequence.

Switch with a rollback

Version the consumer and event schema. Define the cutover timestamp, dual-write or dual-read period, monitoring owner, and rollback trigger. After switching, compare event counts and state transitions by cohort. If events fail verification or suppression updates stop, route to the old adapter or a safe queue, preserve raw events, and investigate before replaying.

Related resources

The Email Infrastructure academy covers the systems around the event contract.

This workflow should be checked against the cited standards and current provider documentation 1.

Cutover edge cases

Plan for events that arrive during the dual-read window, events signed with an old secret, and provider retries after the consumer has acknowledged a request. Make the cutover timestamp and replay boundary explicit. If a provider cannot replay historical events, retain the raw fixtures and application state needed to reconcile the gap without inventing a delivery result.

References