What is Webhook?

Push instead of polling

There are two ways to find out whether something changed in another system. The first is polling: asking the other side's API at a fixed interval whether anything is new. Most answers are “no”, so polling wastes requests, and an event can go unnoticed for up to a full interval. The second is push: the other side tells you, at an address you choose, as soon as the event happens. Webhooks are the most common form of push on the web.

How the flow works

1. The receiving system exposes an HTTPS endpoint, e.g. https://example.com/hooks/payments.
2. That URL is registered with the sending service, through its dashboard or API, together with the event types to subscribe to.
3. When an event occurs, the sender makes an HTTP POST to the URL with the event data, usually as JSON.
4. The receiver verifies the request, stores it and quickly returns a 2xx response.

POST /hooks/payments HTTP/1.1
Content-Type: application/json
X-Signature: t=1759400000,v1=5f2b9c0e...

{"id": "evt_8812", "type": "payment.succeeded", "data": {"orderId": 1042, "amount": "1499.90"}}

Header names and signature formats differ between providers; X-Signature above is illustrative only.

Verifying signatures

A webhook endpoint is a public URL, so anyone who learns it can post a fake “payment succeeded” event. Serious providers therefore sign every delivery with a secret shared only between the two sides, most often as an HMAC-SHA256 of the request body sent in a header: GitHub uses X-Hub-Signature-256, Stripe uses Stripe-Signature. GitHub's validation guide is a good reference implementation. On the receiving side:

• Compute the signature over the raw request body, not over JSON you have parsed and re-serialized; a single changed space breaks the match.
• Compare signatures with a constant-time comparison function.
• If the signature includes a timestamp, reject deliveries older than a short tolerance to limit replay attacks.
• Keep the secret in an environment variable or a secrets manager, never in source code.

Retries and duplicate deliveries

When the sender gets no successful response (a timeout, a 5xx, a dropped connection), it usually retries with increasing delays; how often and for how long varies by provider. The consequence is that the same event can arrive more than once. Delivery is typically “at least once”, not “exactly once”, and events are not guaranteed to arrive in the order they were sent.

Webhook handlers therefore need to be idempotent: record each event ID (evt_8812 in the example), and if an ID you have already processed shows up again, return 200 without doing anything. Otherwise one order can produce two invoices, or a customer can get the same email twice.

Building a dependable receiver

• Respond fast: verify the request, put it on a queue and do slow work such as invoicing or sending emails in the background. Long-running handlers cause sender timeouts and needless retries.
• Choose status codes deliberately: senders decide whether to retry based on the HTTP status code. Return 4xx for a bad signature and 2xx once the event is safely stored.
• Don't treat the payload as the source of truth: for critical flows, fetch the current state from the sender's REST API after the event arrives.
• Plan for missed events: webhooks trigger most automation workflows, and one silently lost event can leave a process half done. A periodic reconciliation job that compares both systems closes that gap.