- The difference between asking an API and being notified by a webhook
- How a form submission or payment notice reaches you
- What the receiver should check (sender, signature, redelivery) and how to notice when notices stop
The short answer
A webhook is a way for a service to send a notice to a URL you set up in advance whenever something happens. With an API, you ask "is there anything new?" yourself; with a webhook, the side that starts the exchange is reversed. It is convenient, but the receiving side has to handle two things on its own: confirming that a notice is genuine, and noticing when notices fail to arrive.
Asking versus being told
An API is a gateway that lets a program use another service's functions or data in a fixed way. To learn about new orders through an API, you have to keep asking every few minutes. This is called polling.
| Point | Polling (API) | Webhook |
|---|---|---|
| Who starts | The side that wants the data | The side where the event happened |
| How fast it arrives | Depends on how often you ask | As soon as it happens |
| Good for | Occasional checks, few items | Knowing about events right away, many items |
For example, the official documentation of GitHub, a service used for software development, also explains that polling can quickly use up API rate limits when you monitor many resources, and that it suits occasional checks or a small number of resources.
How quickly you find out depends on how often you ask.
The receiving side should verify the sender and have a way to notice when deliveries stop.
Following the flow with a familiar example
As a fictional example, consider posting a message to your team chat whenever someone submits your contact form.
- Register the URL that will receive notices with the form service
- Someone submits the form
- The form service sends the submission to that URL over HTTP
- The receiver reads it and posts to the chat
Notifying your accounting system when a payment comes in follows the same pattern.
What the receiving side should watch
The URL that receives notices is reachable from the outside. Anyone can send a fake notice to it, so you need a way to confirm the sender. GitHub's documentation describes the following practices. Other services do this differently, so check the official documentation of the service you use.
- Set a secret and use the signature on each delivery to confirm it is genuine. Do not put the secret in the URL
- Receive over HTTPS
- Reply within 10 seconds that you received it, and do heavy processing afterwards
- Failed deliveries are not redelivered automatically; deliveries from the past 3 days can be redelivered manually
Because the same notice can arrive twice, for example after a redelivery, build the receiver so that it does not process anything twice.
How to notice when it stops
When a webhook stops arriving, nothing happens, so it is easy to miss. Keep a log of notices received and failures, and from time to time fetch a list through the API to check for gaps. When the chat channel or person receiving notices changes, it is also easy to forget to update the registered URL.
In summary
Checklist
- Did you list which services send notices to which URLs?
- Do you confirm the sender, for example with a signature?
- Is the secret kept out of the URL?
- Can the receiver cope if the same notice arrives twice?
- Do you have records or a routine that would reveal missing notices?
One thing to check today
In a service you use, check where notices are set to go when something happens.