Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 15 of 16

Webhooks

0 of 16 complete

Why it matters

Polling an API for changes wastes requests and adds latency, so providers push events to a URL. That inversion moves responsibility to the receiver: the endpoint is public, the sender retries on failure, and anyone can post to it. A webhook integration is therefore a small security and reliability problem, not a notification convenience. The signature proves the sender, the event id makes the handler idempotent, and a queue absorbs the burst.

Mental model

A webhook is a delivery to your front door: anyone can knock, so you check the courier's seal before accepting the parcel. The metaphor breaks because the same parcel may be delivered twice, out of order, or hours late, and the courier expects a signature within seconds.

How it works

Event, rejection, retry, idempotencyInteractive

Delivery is at-least-once. The first attempt fails on purpose, so the retry, the signature scope, the idempotency claim, the enqueue and the fast acknowledgement are visible rather than assumed.

Provider

event sender

Endpoint

public receiver

Store

dedupe + queue

Step 1/6 · event
POST /hooks · signedcall · Provider → Endpoint
POST /hooks/billing HTTP/1.1
webhook-id: evt_9f2c
webhook-timestamp: 1794992800
webhook-signature: v1,k5Df...

{ "type": "invoice.paid",
  "data": { "invoiceId": "inv_221" } }

1794992800 = 2026-11-18T09:06:40Z.
HMAC-SHA256 over
  webhook-id.webhook-timestamp.body
using the exact body bytes received.

Step 1: event. Hover, tap or tab to any message to inspect its payload.

Figure. A webhook is correct only after a failure: the first delivery is rejected with a 503, the provider retries the same event id, and the receiver claims that id and enqueues the event before any work. The signature binds the id, timestamp and body; the 2xx is sent after the claim and enqueue, not after processing.

What to notice. The failure is replay and duplicate side effects. A signature over the body alone does not bind the id or timestamp, so a captured body can be replayed inside the tolerance window; and a 2xx sent after slow processing turns the handler into a retry storm. Ordering is not guaranteed either: an older event can arrive after a newer one.

Text version

Sequence across Provider, Endpoint and Store. Step 1, event: Provider to Endpoint POST /hooks/billing with webhook-id evt_9f2c, webhook-timestamp 1794992800 and a v1 signature computed with HMAC-SHA256 over webhook-id.webhook-timestamp.body, plus a JSON invoice.paid body. Step 2, non-2xx: Endpoint to Provider HTTP 503 with Retry-After 2; the signature and timestamp are valid but nothing was processed. Step 3, retry: Provider to Endpoint the same webhook-id with timestamp 1794992803 and a new signature. Step 4, idempotency: an in-process Endpoint to Store hop claims the event id and enqueues it; Store to Endpoint the in-process result claimed true, enqueued true, firstSeen 2026-11-18T09:06:43Z. Step 5, ack: Endpoint to Provider HTTP 200 after claim and enqueue, before processing. Step 6, process: an in-process worker on Store applies the effect once in a transaction with a unique constraint on the event id.

  1. Register an HTTPS endpoint and store the signing secret in a secret manager, not in the application config.
  2. Read the raw body, verify the signature over the exact bytes with the timestamp, and reject anything outside the tolerance window.
  3. Parse only after verification, and reject events whose id has already been processed.
  4. Acknowledge with a 2xx quickly, then enqueue the payload for asynchronous processing.
  5. Handle out-of-order events by comparing an event sequence or resource version, and ignore stale updates.
  6. Log the event id, signature result and processing outcome, and expose a replay path for failed events.

Trade-offs

ChoiceGood forCostFails when
Synchronous processing in the handlerSimple codeTimeouts trigger retries and duplicatesThe work takes more than a second
Queue and workerFast acknowledgement and retriesInfrastructure and duplicate handlingThe volume is a few events a day
Signature verification onlyProves the senderNo replay protection without a timestampAn old signed payload is replayed
IP allowlistBlocks casual abuseProvider addresses change and shared infrastructure breaks itThe sender uses a CDN or many regions
Trade-off mapInteractive

Good for

Simple code

Cost

Timeouts trigger retries and duplicates

Fails when

The work takes more than a second

  1. The work takes more than a second
  2. The volume is a few events a day
  3. An old signed payload is replayed
  4. The sender uses a CDN or many regions

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Synchronous processing in the handler is good for Simple code, costs Timeouts trigger retries and duplicates, and fails when The work takes more than a second. Queue and worker is good for Fast acknowledgement and retries, costs Infrastructure and duplicate handling, and fails when The volume is a few events a day. Signature verification only is good for Proves the sender, costs No replay protection without a timestamp, and fails when An old signed payload is replayed. IP allowlist is good for Blocks casual abuse, costs Provider addresses change and shared infrastructure breaks it, and fails when The sender uses a CDN or many regions

Failure modes

  • Signature checked on parsed JSON. Re-serialising changes the bytes and verification fails or is skipped. Debug: compute the signature over the raw body and compare with the header before any parsing.
  • Duplicate processing. A retry after a timeout sends the same event twice and the side effect repeats. Debug: count processed events by id and check for a unique constraint or a dedupe store.
  • Replay window too wide. A captured request is accepted hours later. Debug: log the timestamp delta and reject anything beyond the configured tolerance.

In production

Monitor delivery failures, signature rejections and processing lag per event type. Keep a dead-letter queue and a replay tool, because the provider will not resend an event you acknowledged.

Common misconceptions

People think: A webhook fires once.

Actually: Delivery is at-least-once with retries, so duplicates are normal and must be handled.

People think: A secret URL is authentication.

Actually: The URL can leak through logs and referrers; only a signature over the payload proves the sender.

Interview angle

A strong answer covers signature verification over raw bytes, replay windows, idempotency and fast acknowledgement. It also mentions ordering. Weak answers describe registering a URL and parsing JSON.

Sources