Webhooks & Callbacks in OpenAPI/Swagger

Webhooks and callbacks are mechanisms in OpenAPI that enable asynchronous communication beyond the traditional request-response model of REST APIs. Webhooks allow an API to send real-time data to a user as soon as an event occurs, requiring the user to subscribe to the event stream and provide a URL for data reception. In contrast, callbacks enable users to specify a URL for receiving asynchronous responses to long-running API requests. OpenAPI introduced callbacks in version 3.0 in 2017 and webhooks in version 3.1 in 2021. Webhooks are defined as top-level entries in the OpenAPI schema, while callbacks use runtime expressions to resolve URLs dynamically. The blog emphasizes best practices for implementing webhooks and callbacks, such as ensuring idempotency and protecting APIs from DDoS attacks. Although OpenAPI supports asynchronous APIs, the AsyncAPI standard, which is still in early development, may offer more optimized solutions for certain use cases.