Skip to content
API Design Learn/Production REST I: Performance & Reliability
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Webhooks

4 min read

You'll learn to

  • -Explain a webhook as the API calling you when something happens, instead of you polling it
  • -Sign each delivery with HMAC and verify it in constant time, and watch tampering get rejected
  • -Survive retries by giving every event a stable id, and handle out-of-order delivery

A webhook turns the usual direction around. Instead of a client repeatedly asking an API "anything new?" (polling), the API calls a URL the client registered in advance, the moment something happens. It is efficient, because nothing is wasted on empty polls. But it brings problems polling never had: is the call genuine, will it be delivered, and in what order?

An Analogy: The Doorbell

Polling is walking to the front door every minute to check whether the parcel arrived. A webhook is the delivery driver ringing the bell. That is better, but now you have to check that the person at the door really is from the courier, and what to do if the bell rings twice for the same parcel.

HMAC Signing: Proving the Payload Is Genuine

A webhook receiver cannot tell whether a request claiming to be from your API really came from you. Anyone who finds the URL could send a forged payload. The fix is to sign each payload with a shared secret agreed when the webhook was registered. An HMAC (hash-based message authentication code) is a short value computed from the message and the secret: only someone who knows the secret can produce the right one for a given message.

The delivery, with a verifiable signature
POST https://client-app.example.com/webhooks/orders
X-Webhook-Signature: sha256=7d38cdd689735...
Content-Type: application/json

{"event": "order.shipped", "order_id": 501, "shipped_at": "2026-08-07T10:00:00Z"}

The receiver recomputes the HMAC over the raw bytes it received and compares it to the signature header (the code is in the demo below). If they match, the payload came from someone who knows the secret, and was not altered on the way. The comparison must be constant-time (hmac.compare_digest, not ==). A normal comparison stops at the first differing character, and the tiny timing difference can let an attacker guess the signature one byte at a time.

Retries and Idempotent Receivers

A receiver might be down, slow, or return an error. The sender needs a retry policy, usually exponential backoff over a bounded window, not one attempt and give up. But retries mean the same event can arrive more than once. So every event needs a unique, stable id that the receiver can use to spot and ignore a duplicate. This is the idempotency-key idea from earlier in the course, applied to inbound events.

The demo plays four deliveries in a row. The first is genuine and is processed. The second is a retry of the same event and is recognized as a duplicate. The third has one digit changed in transit, and the fourth is signed with the wrong secret. Both of the last two are rejected.

Press Run: genuine, duplicate, tampered and forged deliveries

Webhooks do not guarantee order. Two events fired close together can arrive swapped, especially across retries. If order matters, include a sequence number or timestamp in the payload so the receiver can detect and handle out-of-order delivery, instead of assuming arrival order equals event order.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design The Webhook Wire in the API Design Lab's Production Patterns act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!