A webhook is an input to your application. Verify its signature and delivery identifier before changing state, then preserve the difference between transport events and recipient behavior.
Verify the raw request
Read the exact UTF-8 request bytes before parsing JSON and compute the documented HMAC with your webhook secret. Compare the supplied signature in constant time and reject malformed values.
Keep secrets outside logs and source files. Do not reconstruct the signed body from parsed fields because whitespace and escaping are part of the signature input.
Make processing idempotent
Use the stable delivery or event identifier as your deduplication key. Record the attempt before applying a state transition so a repeated webhook cannot create a second side effect.
If an attempt lease expires, treat the result as unknown until reconciled. Do not invent a success status from a missing callback.
Separate event types
Provider acceptance, later delivery, bounce and complaint observations answer different questions. Store them separately and keep unavailable inbox-placement data unavailable.
Return the documented response quickly after durable processing. Slow or repeated failures can cause another attempt, so your handler must tolerate delivery retries.
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.