All posts
Guides
· 6 min read
Idempotency keys: the two lines that prevent double charges
Retries are only safe if the receiver can tell a repeat from a new event. Here is the key, the header and the storage rule that make that true.
DO
Daniel Okafor
Developer Advocate
Every retry system eventually sends the same event twice. Networks drop acknowledgements, endpoints time out after processing, and a healthy attempt looks identical to a failed one from the outside. The fix is not fewer retries. It is making repeats harmless.
What the key is
Hookline attaches an Idempotency-Key header to every attempt. The value is stable across retries of the same event and changes only when you send a genuinely new event. On your side, the rule is simple: store the key with the result of the first successful handling, and if you see it again, return that result without doing the work.
The SDK generates the key for you from the event id, so you rarely set it by hand. When you replay an event from the dashboard the key is preserved, which is what makes replay safe to run against production.
Where to store it
A unique index on the key in the same database transaction as your side effect is the only pattern that is correct under concurrency. Caches and in-memory sets fail the moment you run two replicas. Keep keys for at least as long as your longest retry window, which on Hookline is 72 hours by default.
Two lines of code, one index, and double charges stop being an incident category.
Ship your first webhook in five minutes.
Buy this template
$49