Webhooks
Webhooks push events to subscriber HTTP endpoints in near real time, replacing constant polling with signed, retried deliveries that consumers must verify and deduplicate.
Definition
A webhook is a user-defined HTTP callback: the provider sends an event payload to a URL the consumer registered, usually signed and retried, so the consumer reacts without polling the provider.
Context and scope
Use webhooks when consumers need timely notifications about events you own, and when polling would waste requests or add unacceptable latency.
Common misconceptions
- Delivery happens exactly once; most providers retry, so handlers must be idempotent
- A 2xx response means the event was fully processed; it only acknowledges receipt
- Webhooks are secure because the URL is secret; URLs leak, so payload signatures are required
Anti-patterns
- Doing slow work inline before acknowledging the delivery
- Trusting payload fields instead of refetching authoritative state
- Registering a public endpoint without signature or replay-timestamp verification
Related concepts
Related examples
Authoritative source
How it works
A provider emits an event — order.paid, user.created, build.finished — and looks up the endpoints subscribed to that event type. It sends an HTTP POST with a JSON payload and a signature header derived from a shared secret. The receiver verifies the signature, acknowledges quickly with a 2xx, and processes the event asynchronously.
POST /hooks/orders HTTP/1.1
Content-Type: application/json
X-Signature: t=1750000000,v1=5f2c...
X-Event-Id: evt_8f21
{"type":"order.paid","data":{"order_id":"ord_123"}}Because delivery usually happens at least once, handlers must be idempotent: store the event id and skip duplicates. Ordering is rarely guaranteed, so consumers should treat events as hints and refetch the authoritative resource when the payload is not enough.
When to use it
Use webhooks when the consumer needs to react promptly and polling would be wasteful: payment confirmations, CI results, chat messages, inventory changes. If the consumer is inside your own trust boundary and you control both sides, a message queue or event stream is usually more reliable than outbound HTTP.
Trade-offs
Webhooks invert control: your endpoint becomes public attack surface, and the provider’s retry policy becomes your traffic. Slow handlers trigger retries that multiply load. The provider cannot see inside your system, so a 2xx acknowledges receipt, not success. Good implementations add signing secrets, replay windows, dead-letter handling, and a delivery log for debugging.
Misconceptions
A secret URL is not authentication. Retries are not a guarantee of eventual processing if your handler silently drops failures. And a webhook payload is a snapshot, not a source of truth.
Related concepts: Idempotency, Retry Budget, and Outbox Pattern.