What Is a Webhook? – Definition and How It Works

Learn what a webhook is, how it inverts polling, how delivery and signature verification work, and what a receiver must handle to be reliable.

A webhook is an HTTP request a service sends to a URL you supply, when something happens. It reverses the usual direction: instead of your system asking repeatedly whether anything changed, the service tells you.

1. What Is a Webhook?

It is a callback delivered over HTTP.

• Key idea: the provider becomes the client and your endpoint becomes the server.
• Mechanism: you register a URL; the provider POSTs a JSON payload describing the event.
• Goal: near-real-time notification without polling.

Example Payload

{
  "id": "evt_01H9",
  "type": "order.completed",
  "created": 1767225600,
  "data": { "order_id": "A-4192", "total": 49.90 }
}

2. Webhooks Versus Polling

Polling is simpler and more forgiving. Webhooks are cheaper and faster, at the cost of operating an endpoint that must always be available.

3. Verifying the Sender

An endpoint that accepts any POST is an open door. Providers therefore sign each delivery, typically with an HMAC over the raw body using a shared secret, sent in a header alongside a timestamp.

The receiver recomputes the signature over the raw body — parsing and re-serialising first will change the bytes and break verification — compares it in constant time, and rejects deliveries whose timestamp is outside a small window to prevent replay.

4. What a Receiver Must Handle

• Idempotency. The same event can arrive more than once. Deduplicate on the event id and make processing safe to repeat.
• Out-of-order arrival. Events are not guaranteed to arrive in the order they occurred; use the payload's timestamp or sequence, not arrival order.
• Fast acknowledgement. Return 2xx quickly and do the real work asynchronously; slow handlers cause the provider to time out and resend.
• Failure semantics. Non-2xx responses trigger redelivery on the provider's schedule, so a bug that returns 500 can produce a flood.

5. Operating the Endpoint

• Expose it over HTTPS only, with a path that is not guessable.
• Log the raw body and headers before processing, so failures are diagnosable.
• Provide a catch-up mechanism — most providers offer an events API to reconcile after downtime.
• Keep the signing secret in a secret manager and rotate it using the provider's overlap window.

6. Common Misconceptions

• "Delivery is guaranteed." Providers retry, but sustained downtime can exhaust the schedule and drop events. A reconciliation path is required.
• "HTTPS is enough authentication." It protects transport. Signature verification is what authenticates the sender.
• "Order is preserved." It rarely is, and building on arrival order produces intermittent, hard-to-reproduce bugs.
• "One event, one delivery." At-least-once is the norm; idempotency is mandatory.

7. Real-World Examples

• A payment provider signalling that a charge settled.
• A repository host notifying a build system that a branch was pushed.
• A form service posting a new submission into a workflow.
• A monitoring pipeline pushing a change notification to a downstream system instead of exporting on a timer.

8. Summary

A webhook delivers an event to your endpoint as an HTTP POST, replacing polling with push. The provider's side is simple; the receiver carries the real requirements.

Verify the signature over the raw body, deduplicate on event id, acknowledge fast and process asynchronously, and keep a reconciliation path for the deliveries that inevitably go missing.

Potential Related Glossary

• Data Structure
• Parsing
• Axios
• Data Fusion