Webhook

Why they exist

The alternative is polling — calling an API every minute to ask whether anything changed. That is wasteful when nothing has changed and slow when something has. A webhook makes the event push-based: Stripe calls your endpoint the moment a payment settles, GitHub calls it when a branch is pushed, a form service calls it when a submission arrives.

The requirement that follows is easy to miss: you need a publicly reachable URL that accepts POST requests. A browser-only app cannot receive a webhook, because there is nothing for the sender to call. You need a server, a serverless function or a platform endpoint. During development, a tunnel such as ngrok or the Stripe CLI stands in for that.

The four rules of handling one properly

1. Verify the signature. The endpoint is public, so anyone who finds the URL can post to it. Providers sign each payload with a shared secret; if you do not verify it, a forged request can mark an order paid. This is the single most common security mistake with webhooks.
2. Respond quickly, work afterwards. Return 200 within a couple of seconds and do the real processing in the background. Slow handlers get treated as failures and retried.
3. Expect duplicates. Retries and network hiccups mean the same event can arrive twice. Store the event ID and ignore ones you have already processed — the alternative is charging or emailing a customer twice.
4. Expect them out of order. payment.succeeded can arrive before order.created. Handlers should look at the current state rather than assume a sequence.

Most providers retry failed deliveries with backoff for hours or days, then disable the endpoint. A dashboard of recent deliveries is usually the fastest way to debug why nothing arrived.

Not the same as an API you call

The misconception is treating webhook and REST API as competing choices. They are complementary: the webhook tells you something happened, and you usually then call the provider's API to fetch the authoritative current state rather than trusting the payload alone.