Bounce Webhook Idempotency and Suppression State
Process bounce events once, preserve ordering evidence, and derive a stable suppression state even when webhooks retry or arrive late.
Product & Engineering · September 25, 2026 · 2 min read
Before you start
Start with the decision boundary: event processing should be safe to repeat: the same provider event must not produce a different suppression decision on each retry. is evidence for a sending decision, not a guarantee of acceptance, inbox placement, relevance, permission, or replies. Keep the original value, the observation time, and the rule that converted evidence into an action. This makes a list change explainable when a later event disagrees.
A practical workflow
1. Select the idempotency key
Prefer a provider event ID; otherwise derive a conservative key from message ID, recipient, event type, and observed time. Store the raw payload location or hash for audit without inventing fields the provider did not send.
2. Separate receipt from application
Acknowledge or queue the event only after durable receipt, then process it with retries and a dead-letter path. Do not make a transient consumer error look like a successful suppression.
3. Handle ordering explicitly
Use event time and precedence rules when a soft bounce, hard bounce, correction, or manual review arrives out of order. Keep every event and derive current state rather than mutating history.
4. Verify destination state
After applying the rule, check the suppression record or send gate and reconcile failed propagation. SES documents account- and Region-scoped suppression behavior; your application may need a broader cross-system control.
Decision table
| Situation | Evidence to retain | Default action |
|---|---|---|
| First delivery | Event ID and recipient key | Apply state transition once |
| Duplicate retry | Same idempotency key | No-op with audit count |
| Late hard bounce | Event time and prior state | Apply precedence; preserve timeline |
| Dead-letter event | Payload reference and error | Block or review affected path |
Edge cases and guardrails
Provider event payloads and guarantees differ. Use provider-neutral fields in your design and map only documented values. A webhook handler that simply toggles a boolean can reopen a suppressed address when an older event is replayed.
How this fits with list operations
Pair this engineering runbook with outbound suppression rules for state precedence and email verification statuses for non-event classifications. Use the hard versus soft bounces guide for the delivery meaning of each class. Start with the lead-generation academy, then use the list hygiene checklist for the audience gate, the verification status model for technical outcomes, and the outbound suppression rules for cross-system enforcement.
Add tests for duplicate delivery, retry after partial success, event IDs reused across tenants, an old event after a newer state, and a dead-letter replay. These cases are more revealing than a happy-path webhook test.
Sources
Resources in this guide
| Situation | Evidence to retain | Default action |
|---|---|---|
| First delivery | Event ID and recipient key | Apply state transition once |
| Duplicate retry | Same idempotency key | No-op with audit count |
| Late hard bounce | Event time and prior state | Apply precedence; preserve timeline |
| Dead-letter event | Payload reference and error | Block or review affected path |
Common mistakes to avoid
- Treating a verifier result as proof that a message will be accepted or reach the inbox.
- Letting a newer import automatically clear an unsubscribe, complaint, bounce, or manual block.
Frequently asked questions
What does idempotent mean here?
Reprocessing the same event produces the same outcome and does not duplicate or weaken the suppression state.
Should a webhook handler delete old events?
No. Keep enough event identity and timing evidence to explain and recompute current state.
What happens when events arrive out of order?
Apply documented precedence using event metadata, preserve the full timeline, and route ambiguous conflicts to review.
Continue learning
Validate the resulting suppression state
Continue from the decision model into a repeatable list-quality control.