LESSON 03 OF 05 · 15 MIN

Webhooks, External Events & Secure Inputs

Taking messages from other systems without trusting everything that turns up at the door.

A courier knocks with a parcel. Before you sign, you check a few things without thinking about it: is this the company I ordered from, is the name right, and — if a second identical parcel turns up tomorrow — do I actually owe for two, or did they just deliver the same thing twice?

So what is this really about?

Software receives parcels too: messages from other systems saying something happened. The same questions apply. Is this really from who it claims? Is it the right shape? And if it arrives twice, does that mean two of something, or one thing delivered twice? That last question causes more real damage than the others combined.

Two identical deliveries are matched on the sender’s reference, so only the first creates anything.

QUICK CHECK

Your payment provider sends the same "payment received" message three times because of a network hiccup. What should your system do?

The words you will hear

Webhook: A message another system sends you when something happens. Your parcel.
Signature: Proof the sender is who they say. The courier’s ID, checked rather than assumed.
Duplicate delivery: The same message arriving twice. Normal, expected, and must be harmless.
Idempotent: Handling the same message twice leaves you exactly where handling it once did.

What you will be able to do

List what must be verified before a webhook payload is trusted.
Make an endpoint idempotent so duplicate delivery is harmless.
Explain why acknowledging quickly and working afterwards is the correct shape.

Going deeper

Four checks at the door

A message from another system is a parcel from a stranger. Four questions, in this order, before it means anything.

1Is it really from them? A signature you verify, not a name you believe. An unsigned webhook is an anonymous request.
2Is it a sensible size? Reject anything implausibly large before reading it into memory — and measure as you read rather than trusting the declared length.
3Is it the right shape? Validate against your schema, exactly as with a model reply.
4Is it fresh? A correctly signed message replayed next week is still correctly signed.

YOUR TURN

Why check the signature before the shape?

The duplicate problem

This is the one that causes real damage, and it is worth being blunt about why: every serious sender retries. If they do not get a clean reply quickly, they send again. They are right to — the alternative is losing your data when your server has a bad second.

WHAT WOULD YOU DO?

How do you stop the same message being processed twice?

Check whether we have seen this id, then insert — There is a gap between the check and the insert. Under a retry storm — exactly when this matters — two requests land in that gap and both pass the check.

Put a uniqueness rule on the id and just insert — Right. The database decides, atomically. The second insert fails, you catch that, and you return success without doing the work again.

Keep recent ids in memory — Works until you restart, or run a second copy of your service. Both of which will happen.

A quick way to test whether your endpoint is finished

Send the same message twice on purpose. If the second one changes anything at all — a second row, a second email, a second charge — it is not finished yet.

Say yes fast, work afterwards

If you validate, save, call a model, send an email and only then reply, you have made the sender wait for every one of those. Any failure means they retry all of it.

The sender is released as soon as the message is safely recorded.

Write it down, say yes, then do the slow part.