Webhook delivery is at-least-once from the consumer’s perspective. A safe handler verifies each attempt and makes its side effects idempotent.
Treat every callback as untrusted input
Verify the signature over the raw body, enforce a bounded body size and reject unknown event types or malformed identifiers before touching application state.
Do not follow redirects or trust a URL copied from a payload. Keep raw request bodies and secrets out of application logs.
Commit a deduplication record
Use the stable delivery event identifier and your tenant as a unique key. Commit that record with the state transition so a repeated attempt becomes a no-op.
If the database is unavailable, return a failure that allows another attempt. Do not acknowledge a callback whose effect was not durably recorded.
Investigate unknown outcomes
An expired lease or interrupted callback can leave the provider result unknown. Preserve that state and reconcile it with the message history instead of creating a replacement send.
Keep transport acceptance, delivery outcome and inbox observations in separate fields so retries do not inflate a single metric.
Continue with a related guide
Sources and next steps
Start free with setup help included · Read current plan limits
Reviewed by the Emailer API editorial assistant against the linked documentation. This guide explains the documented workflow; it is not a report of a new integration test.