A webhook is a reverse web API: an HTTP request that an API provider sends automatically to a consumer when an event occurs. It enables near-real-time notification without repeated polling, reducing unnecessary infrastructure load. section 14.6 section 14.6.1
Banking transaction notifications
A third party configures a consumer-owned notification URL, such as https://consumer.com/notifications, in a banking developer portal. When a transaction occurs, the provider sends a POST request containing transaction information. Consumers without a webhook-capable backend can instead retrieve transactions through regular API operations, accepting less timely updates. section 14.6.1 section 14.6.2
Design a webhook around these decisions:
- Make it optional when consumers can reasonably use regular API calls without infrastructure problems. section 14.6.2
- Use POST, let consumers choose the implementation path, and define the event contract for interoperability and efficient processing. section 14.6.3 section 14.9
- Expose only necessary data; choose protections such as message signatures, IP allowlisting, mutual TLS, or OAuth 2.0. section 14.6.6
- Require a fast 2XX acknowledgment, then process the event asynchronously through a database or event queue. section 14.6.7
- Plan for timeouts and non-2XX responses with retries, notification history, consumer catch-up operations, or on-demand redelivery. section 14.6.8
Figure 14.7 The banking notification system calls the Transaction Notification webhook to prevent the consumers from polling transactions.
Visualizes provider-to-consumer transaction notification and the polling problem that webhooks address. section 14.6.1
Figure 14.10 Webhooks go under the webhooks property of the OpenAPI document. A webhook doesn’t have a path but an identifier. Other than that, a webhook is defined like any other operation under paths.
Shows how a webhook is represented in OpenAPI under webhooks rather than paths, with an identifier, POST request body, responses, and security. section 14.6.9
