What is a webhook? Explained with a doorbell
A webhook lets one app tell another the moment something happens, instead of being asked over and over. Explained with a doorbell instead of checking the door every few minutes.
- Author
Umair Mateen- Published
- Reading time
- 5 min
- Category
- Engineering
In one sentence: A webhook is a way for one app to tell another app the moment something happens, by sending a short message to a web address you gave it, so your system does not have to keep asking "anything new yet?"
The everyday picture
Imagine you are waiting for an important parcel. Without a doorbell, you would walk to the front door every few minutes to check. Most trips would be wasted. And if the parcel came just after you looked, it would sit outside until your next check.
Now fit a doorbell. You stop checking. You get on with your day, and when the courier arrives, they ring. You open the door, sign for the parcel, and deal with it.
Software has the same choice. One app can keep asking another app for news. That is called polling. Or the other app can ring a bell when something happens. That bell is a webhook.
When something happens, the sending app rings your doorbell: a message to your endpoint. Your system checks the signature, says "got it", and puts the work in a queue.
How it works, step by step
- You give the other app an address (you fit a doorbell and tell the courier which door is yours). This address is a web link on your system, called an endpoint. You also choose which events you care about, such as "payment received" or "order placed".
- Something happens in the other app (the parcel is ready for delivery). A customer pays, a form is sent, or code is changed.
- The app sends a message to your address (the courier rings and hands over a note). The message is usually a short block of data in a format called JSON, sent over a secure web connection (HTTPS). It says what happened and includes the details.
- Your system checks it is real (you look at the courier's ID before signing). The two apps share a secret, and each message carries a signature made with it. If the signature does not match, your system ignores the message.
- Your system says "got it" straight away (you sign for the parcel at the door). It replies with a success code within seconds. GitHub, for example, expects a reply within 10 seconds. Then it puts the job in a to-do tray, called a queue, and does the slower work afterwards.
Try it · Side by side
Checking the door or fitting a doorbell: which suits the job?
Tap what matters to you (pick one or more) and see which option fits.
Checking the door (polling)
- Only as fast as you check, so news can sit waiting
- Many checks find nothing new
- Simple: just ask when you need it
- Nothing to expose to the internet
Doorbell (webhook)
- Told almost straight away
- A message only arrives when there is news
- Overkill to set up for a one-off
- Needs a public, secure endpoint that checks signatures
Pick what matters to you and the better fit lights up.
Where the picture stops
- A missed ring is often tried again. If your system is down or slow to answer, many senders retry later. Stripe, for example, keeps retrying for up to three days. A courier might just leave a card.
- The same news can arrive twice, or out of order. Stripe warns that events can be duplicated and may not arrive in the order they happened. Your system should note each message's ID and skip ones it has already handled.
- Nobody has to be home. The "door" is a computer that answers on its own, day and night, without a person standing by.
Why it matters for your business
- Speed. Your systems learn about a payment or an order almost as it happens, so customers get confirmations and stock updates sooner.
- Lower running cost. GitHub notes that webhooks take less effort and fewer resources than polling, and polling many things can hit the limits a service puts on how often you may ask.
- Risk you must manage. Your endpoint is open to the internet, so anyone could try to ring the bell. Checking signatures and using HTTPS stop fake messages from being trusted.
- Reliability. If you ignore retries and duplicates, you can miss an order or charge for it twice in your own records. A well-built receiver handles both.
Try it · Myth or fact
Webhooks: myth or fact?
Decide for yourself first, then tap each statement to check it.
0 of 3 checked
An example
Imagine a small online bakery that takes card payments through a payment provider. At first, its order system asks the provider every 15 minutes, "any new payments?" Customers sometimes wait a while for their order confirmation.
The bakery's developer sets up a webhook for "payment succeeded". Now, when a customer pays, the provider sends a message to the bakery's endpoint. The system checks the signature, replies "got it", and adds the order to a queue. A moment later, the kitchen screen shows the order and the customer gets a confirmation email. If the same payment message arrives twice, the system sees the ID it already handled and skips it.
Frequently asked questions
What is the difference between a webhook and an API?
With an API, your system asks another system for something when it needs it. With a webhook, the other system tells yours when something happens. Many services offer both, and they work well together.
Is a webhook the same as polling?
No, it is the opposite. Polling means asking again and again on a timer. A webhook means you ask once, when you set it up, and then wait to be told.
Are webhooks secure?
They can be, if set up well. Use HTTPS, keep the shared secret safe, and check the signature on every message before acting on it. Never put passwords or keys in the endpoint address itself.
When should I not use a webhook?
If you only need information once, or now and then, simply asking the API is fine. GitHub's own guidance says the same.
Related explainers
- What is an API? Explained with a waiter in a restaurant
- What is monitoring? Explained with smoke alarms
- What is an AI agent? Explained with an assistant you send on errands
The DevDrift connects business systems with webhooks and APIs, with retries and checks built in: see how.
Sources
Could you explain this to a colleague now?
Mark it and posts that mention it will show a tick. Saved in this browser only.