REALIADADTECH / BUILD & LEARN
← Free Foundations

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.

The same message arriving twice produces one resultTwo identical deliveries are matched on the sender’s reference, so only the first creates anything.Delivery oneDelivery twoSeen this before?only onceOne result
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

Going deeper

A webhook endpoint is a public door into your system. Anyone can knock, they can knock repeatedly, and they can claim to be someone they are not.

Verify before you trust

Four checks, in order, before the payload means anything:

  1. Authenticity. Is this really from the sender it claims? A shared secret or signature, compared in constant time. An unsigned webhook is an anonymous request.
  2. Size. Reject anything implausibly large before reading it into memory. Do not trust a declared content length — measure as you read.
  3. Shape. Validate against a schema, exactly as with a model response.
  4. Freshness. A valid signed payload replayed a week later is still valid. Timestamps and a record of what you have already seen close this.

Idempotency is the whole game

Every serious webhook provider retries on failure, and retries mean you will receive the same event twice. If handling it twice does something twice, you have a bug waiting for a bad network day.

The fix is a stable identifier from the sender and a uniqueness constraint in your database. Let the database reject the duplicate — an application-level "check then insert" has a race between the check and the insert, and under retry storms that race is exactly when it matters.

A useful test: send the same event twice deliberately. If the second one changes anything, the endpoint is not finished.

Acknowledge fast, work after

Senders time out. If you validate, store, call a model, send an email and then respond, you have made the sender wait on every one of those, and any failure means a retry of all of them.

Acknowledge as soon as the event is durably recorded. Do the slow work afterwards. This is what keeps a notification outage from becoming a data-loss incident — the thing that mattered was already saved.