Your app sends an invoice and needs to know the moment it gets paid. A message arrives in your support tool and you want it in Slack instantly. A build finishes and a deploy should kick off on its own. In every one of these cases, one system has news and another system needs to hear it right away. Webhooks are how that news travels. If you have ever wondered how webhooks work, this guide walks through the whole idea from first principles, with plain examples and no jargon left unexplained.
A webhook is a simple promise between two applications: when something happens over here, I will send a message over there. That is the entire concept. The rest is detail, but the detail is where the useful understanding lives.
What a webhook actually is
A webhook is an automated HTTP request that one application sends to another the instant a specific event occurs. People sometimes call it a reverse API, and that nickname is a good way in. With a normal API, your app is the one asking: you send a request, the other server answers. With a webhook, the roles flip. The other server does the asking. When an event fires, it sends a request to a URL you gave it ahead of time, and your app is the one that answers.
That URL is the heart of the setup. It is called the webhook endpoint, and it is just an address on your server that is ready to receive incoming requests. You register it once with the source application, usually in a settings screen or through their API, and from then on that application knows where to reach you. When the event happens, it packages up the relevant information into a payload, almost always JSON, and delivers it to your endpoint as an HTTP POST.
Webhooks versus polling
To see why webhooks matter, it helps to look at the alternative. Before webhooks, the common way to stay up to date was polling: your app asks the other service, again and again on a timer, whether anything has changed.
Imagine checking your mailbox. Polling is walking to the mailbox every ten minutes to see if the mail arrived, most of the time finding it empty. A webhook is the mail carrier ringing your doorbell when there is actually something to deliver. One approach burns effort on a schedule whether or not there is news. The other stays quiet until there is a real reason to speak.
The waste in polling is not hypothetical. Zapier once analyzed roughly 30 million poll requests running through its service and found that about 98.5 percent of them came back empty, spending far more resources than an event-driven approach would. Every one of those empty checks costs a network round trip, server time, and often a slice of a rate limit, all to learn that nothing happened.
When polling still makes sense
Webhooks are not always the answer. Polling is simpler to build, since your app stays in control and only needs to make outbound requests rather than expose a public endpoint. If you only need fresh data every few hours, or the source system does not offer webhooks, a scheduled poll is perfectly reasonable. The rule of thumb: reach for webhooks when you need updates in near real time and want to avoid wasted calls, and reach for polling when periodic checks are good enough and simplicity wins.
How a webhook flows, step by step
Here is the full journey of a single webhook, using a payment as the example.
- An event happens. A customer pays an invoice inside the payment provider. That is the trigger.
- The source builds a payload. The provider gathers the details that matter, such as the amount, the customer, and a status of paid, and formats them as JSON.
- It sends an HTTP POST to your endpoint. The request travels to the webhook URL you registered earlier, carrying the payload in its body.
- Your server receives and acts. Your endpoint reads the payload and does the work: mark the invoice as paid, email a receipt, unlock the feature the customer bought.
- Your server responds. You send back a fast HTTP 200 to confirm you got it. If you do not, the sender assumes delivery failed.
The whole exchange usually takes a fraction of a second. From the outside it looks like magic, but it is just one HTTP request landing on a URL and getting a quick reply. The clarity of that flow, an event on one side and a signal on the other, is exactly the kind of relationship that reads well as a small diagram. It is why so many product and engineering teams keep a shelf of clean visuals on hand. If you build those explainers, the lightning 3D icon for the live event and the server 3D icon for your endpoint make the two roles obvious at a glance.
Making webhooks reliable in the real world
The happy path is easy. Production is where the interesting problems show up, and a few practices separate a webhook integration that quietly works from one that drops important events.
Verify that the request is real
Your endpoint is a public URL, which means anyone on the internet can send it a request. You should never trust a payload just because it arrived. Reputable providers sign each webhook with a secret key, adding a signature header you can check. Your server recomputes the signature from the raw body and your shared secret, and processes the event only if the two match. Skipping this step means someone could fake a paid event and unlock things they never bought.
Respond fast, work later
The sender wants a quick 200, often within a few seconds, or it treats the delivery as failed. So do not do heavy work before you reply. The durable pattern is to accept the webhook, drop it onto a queue, return 200 immediately, and let a background worker do the slow parts like sending email or calling other services. Your endpoint stays snappy and your real processing gets room to breathe.
Expect duplicates and design for them
Because senders retry when they are unsure a delivery landed, the same event can arrive more than once. Your handler needs to be idempotent, a word that just means running it twice has the same effect as running it once. The usual trick is to store the unique event ID that most providers include, and ignore any event ID you have already processed. Without this, a single retried payment could send two receipts or grant a bonus twice.
Plan for failure and retries
Sometimes your server is down or slow when an event fires. Good providers retry failed deliveries on a backoff schedule and often show a log of attempts. Watch for repeated failures, return the right status codes so the sender knows whether to retry, and keep your own record of what you received. Treat every webhook as something that might need to be replayed, and outages become a hiccup instead of lost data.
Where you will meet webhooks
Once you know the pattern, you start seeing it everywhere. Payment platforms use webhooks to tell you about charges, refunds, and failed cards. Version control hosts fire them when code is pushed or a pull request opens, which is how continuous integration pipelines start themselves. Messaging and email tools send them for new messages, deliveries, and bounces. Calendars, form builders, and e-commerce stores all lean on the same mechanism to keep separate systems in step without anyone refreshing a page.
This is also the quiet engine behind a lot of no-code automation. When you connect two apps so that a new form entry creates a task, a webhook is very often the wire carrying that event from one service to the other.
The takeaway
A webhook is nothing more than one app calling a URL on another app to say something just happened, and yet that small idea removes an enormous amount of wasted effort. Instead of constantly asking are we there yet, your systems get told the moment they need to know. Understanding how webhooks work, and handling verification, speed, duplicates, and retries with care, is what turns that simple promise into an integration you can trust. If you are drawing the architecture to explain it to a teammate, browse the Thridy 3D icon library for clean visuals, or sort by use in the icon categories to find the right piece fast.