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.

A partner server needs updates after the original request ends. A webhook is useful when the partner can expose an endpoint but does not want to maintain a streaming connection.

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;