OpenAPI Callbacks and Webhooks

OpenAPI is thoroughly mainstream now with most modern API providers producing a description of their API for both internal and external use. There are a few features that are still without widespread traction, and the callbacks feature is one of those. It's a feature with wide appeal that hasn't seen much support from tooling yet - but that is starting to change.

With more tools implementing the callbacks keyword, a wider selection of API providers are looking to adopt OpenAPI. One common roadblock is for APIs that are truly two-way - they include incoming HTTP requests that aren't callbacks but instead result of an external event. Luckily there's already support for this at proposal stage so these APIs should be able to put OpenAPI adoption on their roadmaps! Let's take a look at the two features and the use cases they serve.

Existing Feature: Callbacks for Async Responses

The callbacks field can be added to any path object, at the same level as
parameters, responses, etc. Here, you can describe any number of HTTP
requests that may arrive in response to an earlier HTTP request. This is super useful if an API response will include something slow or expensive or simply not time-critical! Examples could include:

• Reporting APIs where the user can make an API request to generate a report and
  include a URL to send the report data to once it has been generated.
• Status updates for a request that won't complete instantly (such as a payment transaction or message delivery receipt).

If your API has features like this, then the OpenAPI callbacks feature enables you to describe them along with the rest of your API.

Proposed Feature: Webhooks for Event-Driven HTTP

The proposed webhooks field is a top-level element (warning: naming is very much under discussion and is probably the most important part thing to get right in this proposal!) that behaves exactly like a callbacks element within a path entry does. This is very cool because it means that most tools that support callbacks will be able to support webhooks without a lot of work from the maintainers. The main difference is that instead of being the result of an earlier HTTP call, these incoming requests are the result of an event happening elsewhere. This makes it ideal for APIs that offer features like:

• Notifications of events, my favourite example is the GitHub push event.
• Delivery of data that would otherwise be obtained by polling, such as warehouse stock level updates after a purchase - or even a lorryload of stock delivery!

Increasingly our machines talk to one another in ways that are more
sophisticated that the overnight batch import. Being able to describe HTTP
requests in either direction will be a huge boost for OpenAPI. With the
implementation agreed (although still at proposal stage), APIs and tools can move together to adopt this feature.

Callbacks, Webhooks ... or Both?

There are a few situations where callbacks is a valid way to specify an
incoming HTTP request but webhooks may be preferable. For example, an API that allows subscribing to events under a configuration-related endpoint: it may make more logical sense (for outputs such as documentation) to put the description of the event-driven HTTP requests independently under webhooks than nested under an admin endpoint.

If you want to know more about the webhooks feature, then you can find the proposal in the OAS repo and general discussion (all voices welcome, even if you only drop by to share a +1) is on the github issue. OpenAPI is an open standard and it benefits from community participation so do please all
share your thoughts!