Blog
Webhook Retries and Duplicate Events
At-least-once delivery means the same event arrives twice. Document the event id, the retry schedule, and the signature. Developers who treat the first POST as exactly-once will blame you for double writes.
2026-09-15 · 7 min read · AethelLayer
Say the delivery guarantee in the first paragraph
If you retry on any non-2xx and on timeouts, write that down with the schedule. Developers assume exactly-once until a customer gets charged twice.
Include an event id that stays stable across retries. The body timestamp can change. The id must not.
Signature failures are not retries yet
A bad signature should not look like a timeout. Return a distinct code, do not retry forever from their side, and do not retry from yours if you already know the signature was wrong.
Document raw-body signing. Parsing JSON before you verify is the most common first-day bug, and it rarely becomes a ticket.
Handlers have to store the id
The sample receiver should ignore a duplicate id and return 2xx. A sample that errors on the second delivery teaches them to disable retries.
Your inbox should separate signature mismatches from repeated event ids. They are different bugs.
Capture the event id, not the payload
A probe can hold the event id, the attempt number, and the error code. The payload may contain customer data. Leave it out.
When drafts say they disabled the endpoint, read the duplicate rate before you tell them to turn it back on.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.