A webhook is a way for one system to send an HTTP notification to a URL you registered in advance, whenever something happens. Events such as “payment completed,” “booking created” or “document issued” reach the other system within seconds. The receiving side just waits for notifications to arrive instead of asking again and again. This article explains how webhooks work, how they differ from calling an API on a schedule (polling), and where they are a good fit.
How a webhook works
- The receiver prepares a URL for notifications and registers it in the sender’s console or through its API
- When an event happens on the sender’s side, it sends an HTTP POST to that URL, usually with a JSON body
- The receiver checks the notification and returns a success response (an HTTP status in the 2xx range)
- If no success response comes back, most services resend after a delay
Here is an example body. It carries the event type, when it happened and the ID of the object involved.
{
"type": "booking.created",
"timestamp": "2026-11-07T09:00:00+09:00",
"data": { "booking_id": "bk_0001", "customer_id": "cu_0001" }
}Webhooks vs. polling
Without webhooks, the receiver calls the other system’s API every few minutes to see whether anything new has appeared. This is called polling.
| Aspect | Polling | Webhook |
|---|---|---|
| Direction | You ask every time | The other side tells you |
| Speed | Depends on the polling interval (minutes or more) | Seconds after the event |
| Wasted requests | You call even when nothing is new | Only when something happens |
| API rate limits | Short intervals quickly hit the limit | Barely affected |
| What the receiver needs | A program that runs on a schedule | A URL reachable from the internet |
| Missed events | Picked up on the next poll | Lost once the retry window passes |
GitHub’s documentation makes the same point: webhooks take less effort and fewer resources than polling, and polling tends to use up your API rate limit quickly. That said, when the receiving system cannot expose a URL to the internet, for example a system that lives only inside a corporate network, polling can be the simpler choice.
What the receiver has to do
- Verify the signature. Anyone can call your URL, so check the signature attached to each notification to confirm it really came from the sender. Formats differ between senders, but Standard Webhooks offers a common specification
- Respond right away. If you finish heavy processing before responding, the sender may treat the delivery as failed and resend it. GitHub asks receivers to return a 2xx response within 10 seconds. Put the notification on a queue, respond, and process it afterwards
- Expect duplicates. Retries can deliver the same notification twice. Record each notification’s ID and skip the ones you have already processed
- Do not rely on order. Notifications do not always arrive in the order the events happened. Use timestamps or version numbers to tell old from new, or fetch the latest state from the API when a notification arrives
What the sender has to provide
If your own service sends webhooks to customers’ systems, you need a screen for registering endpoints, signing and key management, retries, delivery logs, and alerts and automatic disabling for endpoints that keep failing. The full scope, and a comparison with handing sending to a dedicated service, is covered in “Build vs. buy for sending webhooks.”
Where webhooks fit, and where they do not
Webhooks fit events you want to know about as soon as they happen:
- Payments succeeding or failing, invoices being paid
- Bookings being created, changed or cancelled
- Document generation or file conversion finishing
- Members signing up for or leaving an external service
They are a poor fit for moving large volumes of data in bulk (a nightly file transfer is more reliable), for receivers that cannot expose a URL to the internet, and for cases where a missed notification would stop the business but nothing would catch events lost after the retry window. In that last case, add a scheduled reconciliation through the API alongside the webhook.
About Webhook Admin
Our Webhook Admin takes over webhook sending. It signs messages in the Standard Webhooks format and retries automatically when delivery fails. It also supports ordered delivery per endpoint, payload transformation, delivery to Amazon SQS and Google Cloud Pub/Sub, polling by receivers, failure alerts, a customer-facing portal and static source IP addresses. Pricing is on the product site.
References
- GitHub Docs: About webhooks
- GitHub Docs: Best practices for using webhooks
- Stripe: Receive Stripe events in your webhook endpoint
- Standard Webhooks
FAQ
What is the difference between a webhook and an API?
An API is an entry point you call to ask another system for data. A webhook is a notification the other system sends to you when something happens. A common pattern is to receive the event by webhook and then call the API to fetch the full details.
What do we need to receive webhooks?
A URL reachable from the internet over HTTPS, and a program that accepts the notifications. When a notification arrives, verify the sender with its signature, return a success response right away and do the heavy work later. The same notification can arrive twice, so you also need a way to detect duplicates.
What happens if a webhook is not delivered?
Most services resend when the receiver does not return a success response, waiting longer between attempts. How many times and for how long varies by service, so check the sender's documentation. Once the retry window has passed the notification is lost, so receivers should be monitored to keep them up.
