Webhooks you can trust, in plain words
Signatures, retries and duplicates explained for the person who has to write the receiving end.
Nº 25 · HeedPost team · Oct 9, 2026 · 2 min read
A webhook is a message one system sends another when something happens. A post is created, a vote arrives, a release is published, and a small HTTP request goes to an address you chose. It's the simplest way to keep other tools in step.
It's also easy to build the receiving end in a way that works in testing and breaks quietly in production. Three ideas make the difference: check who sent it, expect it more than once, and don't depend on the order.
Check who sent it
Your endpoint is a public address. Anyone who finds it can send it something that looks like an event. So every delivery should carry a signature: a value computed from the message and a secret only you and the sender know. Your code computes the same value and compares. If they match, the message is genuine and unaltered.
Two details people miss:
- Sign the raw bytes. Parse the JSON and re-serialise it, and you'll compute a different value. Verify against exactly what arrived.
- Check the timestamp too. Without a freshness window, someone who captured one real delivery could replay it later. Five minutes is a common window.
Expect it more than once
Networks fail. Your server times out, or answers just as the connection drops. The sender can't tell whether you got it, so it tries again. That's the right behaviour, and it means you'll sometimes receive the same event twice.
The fix is simple: every event has an id. Store the ids you've handled, and if one arrives again, acknowledge it and do nothing. This is called being idempotent, and it turns "at least once" delivery into effectively once.
Don't depend on the order
Retries mean events can arrive out of order. A "post moved to Shipped" might land before the "post moved to In progress" that was retried. If your code assumes order, it'll write the wrong final state. When the latest state matters, read it from the API rather than trusting the last event you received.
Answer quickly
Do the minimum when a delivery arrives: verify, store, return success. Then process it in the background. Slow handlers cause timeouts, timeouts cause retries, and retries cause the duplicates you then have to handle.
Choose what you listen to
You rarely need every event. Pick the few your integration uses. It keeps your endpoint quiet and your code simpler.
None of this is hard. It's just easy to skip when the first test works. Five extra lines of code on the receiving side are what make a webhook something you can rely on.