#Webhooks: The API Where the Server Calls You

A webhook is the only API pattern where the server calls you. That inversion is powerful, but it comes with a rule you cannot ignore: never answer late, because the server will retry, and retry, and retry.

#What it is

A webhook is an HTTP POST that a server sends to a URL the client has registered in advance. Instead of the client polling the server every few seconds to ask whether something happened, the client leaves a callback URL and waits. When an event occurs, the server actively POSTs a JSON payload to that endpoint. The client does not need to ask.

Think of it like leaving your phone number with a store. Rather than calling all day to ask whether an item is in stock, you leave your number and wait. When the item arrives, the store calls you. It is simple and efficient. Webhooks are the de facto standard for event notification at companies like Stripe, GitHub, Slack, and Shopify.

#Why it matters

• It saves bandwidth and CPU compared to polling every few seconds, where most requests return empty.
• Notifications are near-realtime because they fire the moment an event happens, not on the next poll cycle.
• It is simple to implement on both sides, since it is just an HTTP POST with no long-lived connection required.
• It is the standard for event-driven integration at major SaaS platforms, so learning the pattern pays off across many services.
• It is easy to understand once you know the gotchas, which are predictable and well-documented.

#How it works

The flow has two phases. First, the client registers a callback URL with the server, often via an API call or a dashboard setting. Second, when an event occurs, the server sends an HTTP POST to that URL with a JSON payload describing what happened. For example, when a Stripe payment succeeds, Stripe POSTs to your endpoint with a payload whose type is payment.succeeded and a data object containing the charge details.

Signature verification is mandatory. Because your endpoint is public, an attacker could forge a POST. Stripe signs the payload with HMAC using a shared secret key. You recompute the HMAC on the raw body and compare it to the signature in the header before processing. If they do not match, you discard the request. Beyond security, you must return a 2xx status as fast as possible. If you return a non-2xx status or time out, the server retries with exponential backoff, and Stripe will retry for up to three days. For heavy processing, enqueue the work and respond immediately.

#Caveats

Webhooks are simple in concept but full of gotchas in practice. The server retries when you return non-2xx, so you must handle duplicate deliveries with idempotency keys. Event ordering is not guaranteed, so event 2 can arrive before event 1, and you need timestamp or version checks to handle out-of-order events. Your endpoint is public and can be DDoSed or spoofed if you skip signature verification. Webhook is one-way, server-to-client, so it is not a substitute for bidirectional realtime communication.

#Who it's for

Webhooks are for developers building event-driven integrations: payment notifications, CI/CD triggers on code push, form submissions, and order status updates. If you need one-way event notification from a server to your system, webhooks are the standard, and doing them right means handling retry, idempotency, and signature verification.

Webhooks are simple but full of gotchas. Get retry, idempotency, and signature verification right, and they become one of the most reliable patterns in your toolkit.

Source: https://developer.github.com/webhooks/