Webhooks: Designing the API That Calls Back

A customer's server polls GET /orders/ord_7M2K every five seconds. Almost every response says the order has not changed, and the one response that matters arrives up to five seconds late.

That customer has no open browser screen, so SSE is not the right boundary. Their server needs to learn about a change after the original request has ended.

With a webhook, your service becomes the caller. That reversal creates a whole outbound contract, and it has eight parts:

• how the customer registers an endpoint;
• what one event contains;