
Polling and webhooks
| Polling | Webhook | |
|---|---|---|
| Who starts the call | You ask | They tell you |
| How fresh | As fresh as your last question | Seconds after it happens |
| Wasted calls | Most of them | None |
| Needs a public URL | No | Yes |
| If your server is down | You ask again later | You depend on their retries |
Receiving one safely
- Verify who sent it. Anyone can call a public URL. Most providers sign each call with a shared secret, and you check the signature before trusting anything in it.
- Answer fast. Say received, then do the work afterwards, usually by putting it on a queue. Providers give up on slow answers and send the event again.
- Expect duplicates. The same event can arrive twice. Store the id of each event and ignore one you have already handled.
- Do not trust the order. The paid event can arrive before the created event.
What the sender does when you do not answer
It tries again, usually several times over a period of hours, with longer waits between tries. Then it gives up. If your server was down for a day, some events are gone, so you still need a way to ask for the current state.
Common mistakes
- Doing all the work before answering, and timing out.
- Skipping the signature check in the first version and never adding it.
- Treating a webhook as the only source of truth. It is a notification. Fetch the current state when it matters.
- Testing only the happy event, and never the refund, the failure or the duplicate.
Questions you will hear in a meeting
- Do we verify the signature?
- What happens if we get the same event twice?
- What happens to events sent while we were down?
- How do we test this on a laptop?
In an interview
If a design includes a payment or any outside service that reports back, say how you would receive its webhooks: verify, acknowledge, queue, and handle duplicates. Those four words show you have done it before.