A webhook is an HTTP callback triggered by an event: when something happens in a source system, that system sends an HTTP request, usually a POST with a JSON body, to a URL that the receiving system registered in advance. Among APIs, webhooks provide push-based notification, the reverse of the usual pattern in which a client repeatedly asks a server whether anything has changed.
Webhooks are sometimes called reverse APIs, because the provider calls the consumer rather than the other way around. They connect payment processors, code repositories, messaging platforms, e-commerce systems and automation tools, and they are typically documented alongside a provider’s REST API.
How a webhook delivery works
A webhook delivery follows a fixed sequence from subscription to acknowledgment. The consumer first registers an endpoint and selects the event types it wants. From then on, the provider sends one request per event without being asked.
| Step | Actor | What happens |
|---|---|---|
| Subscription | Consumer | Registers an HTTPS endpoint and chooses event types |
| Event | Provider | A payment succeeds, a commit is pushed, an order ships |
| Delivery | Provider | Sends a POST with the event payload and signature headers |
| Verification | Consumer | Checks the signature and timestamp |
| Acknowledgment | Consumer | Returns a 2xx status within the timeout |
| Retry | Provider | Resends with backoff if no 2xx arrives |
Providers usually expect a response within a short timeout, often 5 to 30 seconds. Anything slower is treated as a failure. For that reason, a well-designed receiver acknowledges quickly and moves the actual processing to a background queue.
Subscriptions are managed either in the provider’s dashboard or through its API, and many providers keep a delivery log showing each attempt, the response code and the response time. That log is the first place to look when events seem to go missing, and it often allows manual redelivery of failed events.
Webhooks compared with polling and other API styles
Webhooks solve the problem of learning about changes promptly without wasting requests. The main alternative is polling, in which the client asks the API at fixed intervals; other alternatives keep a connection open.
| Approach | Direction | Latency | Main drawback |
|---|---|---|---|
| Webhook | Provider pushes to consumer | Seconds | Consumer needs a public endpoint |
| Polling a REST API | Consumer pulls repeatedly | Up to the polling interval | Many empty requests, rate limits |
| WebSocket | Persistent two-way connection | Near real time | Connection management on both sides |
| Server-sent events | One-way stream from server | Near real time | Client must stay connected |
| GraphQL subscription | Stream over a persistent connection | Near real time | Requires a subscription-capable server |
Webhooks fit server-to-server integration best, where the receiver is always online and events are relatively infrequent. They are poorly suited to browsers or mobile apps, which cannot expose a stable public URL. Many integrations combine both styles: a webhook signals that something changed, and the consumer then calls the REST API to fetch the authoritative current state.
Payloads, delivery guarantees and retries
Most providers deliver webhooks with at-least-once semantics. If the acknowledgment is lost or late, the same event is sent again, so a receiver must expect duplicates and should never assume that events arrive in the order they occurred.
A payload usually contains an event identifier, an event type, a creation timestamp and either the full affected object or only its identifier. Thin payloads carrying just an identifier are safer against stale data, while full payloads save an extra API call.
| Property | Typical provider behavior | Receiver response |
|---|---|---|
| Retries | Exponential backoff over hours to days | Process idempotently |
| Duplicates | Possible after timeouts | Store processed event IDs |
| Ordering | Not guaranteed | Compare timestamps or fetch current state |
| Endpoint failure | Endpoint disabled after repeated errors | Monitor and re-enable, replay missed events |
| Payload size | Usually a few kilobytes | Fetch large objects separately |
Payload formats change over time, so providers usually version their webhook schemas and let consumers choose a version per endpoint. A robust receiver ignores unknown fields and unknown event types instead of failing, logs them for review and upgrades deliberately after testing. Some providers also follow shared conventions, such as the CloudEvents specification, which standardizes metadata fields like event type, source and identifier across vendors.
Securing webhook endpoints
A webhook endpoint is a publicly reachable URL that accepts writes, so anyone who discovers it can send forged requests. Securing it requires verifying that each request genuinely comes from the provider and has not been replayed.
| Measure | Protects against | How it works |
|---|---|---|
| HMAC signature | Forged requests | Provider signs the raw body with a shared secret, usually SHA-256 |
| Timestamp check | Replay attacks | Reject requests older than a few minutes |
| HTTPS only | Interception and tampering | TLS encrypts payload and headers |
| Secret rotation | Leaked secrets | Accept old and new secrets during a transition |
| Constant-time comparison | Timing attacks on signatures | Compare digests without early exit |
The signature must be computed over the raw request body exactly as received. Frameworks that parse and re-serialize JSON before verification change whitespace or key order, which makes valid signatures fail. IP allowlists can add a layer, but providers change address ranges, so they should complement signatures rather than replace them.
Common mistakes when implementing webhooks
Most webhook failures stem from treating a delivery as a reliable function call. In reality, it is a network message that can arrive late, twice, out of order or not at all.
- Heavy processing before responding causes timeouts, retries and duplicate work.
- Missing idempotency leads to double shipments, double emails or double credits when a delivery is retried.
- Skipping signature verification lets attackers trigger business actions with crafted requests.
- Relying on webhooks alone loses events during outages; a periodic reconciliation through the API closes the gaps.
- Testing only the happy path hides problems that appear with retries, unknown event types or schema changes.
The simple explanation
A webhook is a way for one online service to tell another service immediately that something happened. Instead of checking again and again, the second service simply waits to be notified.
It is like the difference between repeatedly calling a shop to ask whether an order has arrived and leaving a phone number so the shop calls back. The webhook is the callback number: the shop calls once, at the right moment, and nobody wastes time asking.
How it is used in practice
An online store uses an external payment provider. Originally, the store polled the provider’s API every minute to check whether pending payments had cleared, which produced thousands of empty requests per day and up to a one-minute delay before orders were confirmed.
The developers register a webhook endpoint for payment events. Each request is verified with an HMAC signature, recorded by event identifier and acknowledged within 200 milliseconds, while a background worker marks the order as paid and triggers fulfillment. A nightly reconciliation job compares orders with the provider’s records. Orders are now confirmed within seconds of payment, and duplicate deliveries no longer cause duplicate shipments.