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.
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.
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.
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.
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.
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.