What is a Webhook? Definition, Security and Retries
A webhook is an HTTP POST a service sends when an event happens. Learn how delivery works, signature checks, retries, idempotency and mistakes.
What is a webhook?
A webhook is an HTTP request, almost always a POST, that one service sends to a URL you registered when something happens on its side. You give the provider your URL once. After that it calls you with a small JSON payload each time an event occurs, such as a payment succeeding or a build finishing. You never have to ask "anything new?".
Webhooks vs polling
Without webhooks you poll: your code calls the provider's API on a timer and checks for changes. That has three costs.
- Delay. With a 60 second interval, an event waits 30 seconds on average before you notice it.
- Waste. Most polls return nothing new, yet each one uses bandwidth and counts against the provider's rate limits (see why APIs rate limit).
- Trade-off. Poll faster and you hit the limits, poll slower and you react late.
A webhook flips it: the side that knows the event happened tells you right away.
How a webhook delivery works
- You register an HTTPS URL with the provider, usually in a settings page.
- An event happens: a customer pays, a pull request is merged, a monitor fails.
- The provider builds a payload, for example
{"event": "charge.succeeded", "data": {"id": "ch_123", "amount": 1500}}, and POSTs it to your URL with headers such as the event type, a delivery ID and a signature. - Your endpoint verifies the request, stores or queues the event and answers with a 2xx status.
- If it answers with an error or not at all, the provider retries later.
Verify every webhook
Anyone who learns your URL can POST to it, so an unverified handler can be tricked into marking orders paid or granting access. The usual defence is an HMAC signature: the provider signs the exact request body with a secret you share (HMAC is defined in RFC 2104) and sends the result in a header. You recompute it and reject mismatches. Stripe uses a Stripe-Signature header and its libraries reject timestamps more than 5 minutes old by default, which blocks replays.
Two details cause most failures. First, sign-checking needs the raw body, so do not let your framework parse and re-serialize the JSON before you verify. Second, compare signatures in constant time. A static bearer token in a header is weaker, because a single captured request can be replayed. An IP allowlist helps as an extra layer but breaks when providers change addresses.
Retries, duplicates and ordering
Delivery is at least once, not exactly once. Stripe retries a failed event for up to three days in live mode, and GitHub expects a 2xx answer within 10 seconds. So your handler will see duplicates, and sometimes events out of order (Stripe does not guarantee order).
- Make handlers idempotent. Store the event or delivery ID and skip IDs you already processed.
- Acknowledge fast, work later. Save the event, return 200, and process it from a queue.
- Do not rely on order. If
order.fulfilledarrives beforeorder.created, fetch the current object from the API instead of trusting the sequence.
Common webhook mistakes
- Skipping signature verification because "nobody knows the URL".
- Parsing the body before verifying, so the signature never matches.
- Doing slow work inside the request, which causes timeouts and then duplicate retries.
- Returning 200 even when saving the event failed, so the provider never retries.
- Testing only on localhost. Use a tunnel or the provider's CLI to forward real events, and replay one with curl to check your handler.
- Never looking at the provider's delivery log, so failures go unnoticed.
Webhooks in monitoring
Webhooks are how monitors hand an alert to your own tooling. In LoadFocus API monitoring, a webhook alert channel sends an HTTP POST with a JSON body to an HTTPS URL you control whenever a check fails, recovers, runs degraded or an SSL certificate is about to expire. The payload carries fields such as event (for example check.failed), the check name and URL, the status, the location and a timestamp. Your endpoint should return a 2xx quickly. Saving the channel sends a one-time confirmation POST, and the setup steps are in the webhook alert channel docs. Keep the receiving URL hard to guess and check the payload fields before acting on it. For the bigger picture, see API monitoring.
FAQ: Webhooks
Is a webhook the same as a callback URL?
Yes. Webhook, HTTP callback and reverse API all describe the same pattern: a service calls a URL you gave it when an event happens.
What is the difference between webhooks and WebSockets?
A webhook is a one-off HTTP request sent by a provider when an event occurs. A WebSocket is a long-lived two-way connection between a client and a server. Use webhooks for occasional events between services and WebSockets for constant two-way traffic such as chat.
What happens if my endpoint is down?
Most providers retry for a while and then give up. Stripe, for example, retries for up to three days in live mode. After that you must replay the events yourself, so watch the provider's delivery log and keep a way to re-fetch missed events.
How do I test a webhook handler locally?
Providers cannot reach localhost, so expose it through a tunnel such as ngrok, or use the provider's CLI to forward events, as the Stripe CLI does. Then replay saved payloads with curl while you debug.
Should I use webhooks or polling?
Use webhooks when latency matters or events are rare. Use polling for bulk syncs or when you cannot run a public HTTPS endpoint. Many integrations combine both: webhooks for speed, an occasional poll to catch anything that was missed.
Related terms
- Asynchronous Loading: async vs defer and Performance
- What is Continuous Delivery (CD)?
- What is Edge Computing?
- What is Expo? React Native Framework, EAS Build and Updates
- Hot Module Replacement (HMR): How It Works
- Incremental Static Regeneration (ISR)
- Infrastructure as Code (IaC): Definition, Tools, Examples
- What is Jamstack?
Related LoadFocus Tools
Put this concept into practice with LoadFocus, the same platform that powers everything you just read about.