Webhook

What a webhook is

A webhook is an automatic notification from one system to another as soon as an event occurs. Think of it as a doorbell: instead of regularly checking whether somebody is at the door, the bell rings. Technically it is a call to an address the receiver provides, carrying a short message about the event.

The direction matters. With an ordinary interface the receiver asks the sender, at fixed intervals and without knowing whether anything changed. A webhook reverses that: the sender reports, and does so when there is something to report.

Why that beats asking

Polling at fixed intervals always costs. It consumes calls even when nothing happened, and it carries a delay of up to half the interval. With stock and prices a delay of minutes is often unproblematic, with an order it is not.

A webhook delivers immediately and only on an event. For orders, payment confirmations and shipping status that is the fitting route, because there a delay becomes visible at once, for instance when the customer has the order confirmation before the shop does.

What has to happen on failure

• Retry: the sender has to repeat a message when the receiver was unreachable. Without retry events are lost.
• Detect duplicates: on a retry the same message can arrive twice. The receiver needs an identifier per event to recognise that.
• Answer quickly: the receiver should confirm at once and do the processing afterwards. If the sender waits too long it gives up.
• Be provable: a signature in the call shows the message came from the expected sender. Without it anyone can call the address.
• Be logged: without a record of arrival and result a fault cannot be traced later.

Where it reaches its limits

The first point is ordering. If two messages arrive close together, it is not guaranteed they are processed in the same order. Anyone relying on that builds errors that are rare and therefore hard to find.

The second point is volume. Anyone sending a message on every small change produces a flood with a large assortment. Consolidation is sensible, for instance one message with several changes instead of one per item. The third point is dependence: a webhook assumes the receiver is reachable. During work on your own system messages have to be buffered and delivered later.

Frequent questions

• Does a webhook replace an interface? No, it complements it. For queries and bulk changes the interface stays necessary.
• Can I test a webhook? Yes, with an address that logs the incoming calls.
• What is the most common mistake? No retry at the sender and no duplicate check at the receiver.