Build an email webhook handler that can recover
Treat incoming delivery events as durable work, and expect duplicate notifications and delayed arrivals.

On this page
Verify before you trust
Webhook requests arrive from outside your application. Follow your provider’s signature-verification procedure before treating the payload as an authentic event. Some schemes verify the raw request bytes, so parsing and rebuilding the JSON first can break verification.
Keep endpoint secrets outside source control and use the provider’s documented replay protections. The event payload should never be enough on its own to authorize unrelated account changes.
Store first, process second
A webhook endpoint should do a small amount of dependable work: authenticate the request, validate its shape, and durably record the event. Return success after that record or queue write succeeds. If persistence fails, do not acknowledge work you have lost.
Process the event asynchronously where possible. Use the provider’s event ID as a deduplication key within the relevant provider account. Duplicate notifications should not create duplicate support alerts or repeatedly apply the same suppression action.
- Record event ID, provider account, message ID, and event time.
- Make downstream handlers safe to run again.
- Keep a bounded recovery path for failed processing.
Keep history instead of guessing the order
Do not assume events arrive in the order they occurred. Store their original timestamps and types, and define how each affects your application state. A late delivery notification should not silently erase a later complaint.
Test duplicates, invalid signatures, a database outage, and an older event arriving last. Your goal is not an endpoint that succeeds once in a demo. It is a handler whose state can be reconstructed after an interruption.
