Providing Webhooks

Webhooks provide bi-directional communications from the API provider to the API consumer to support out-of-band events that do not fit into the pattern of REST APIs or Callbacks. Webhooks describe a pattern where an API consumer registers in advance to receive requests at a URL of their choosing. When an event occurs to trigger a webhook, the server sends a request containing the event data to the registered URL, and the consumer acknowledges it. Webhooks fulfill similar purposes to Callbacks in that they support transmitting information about asynchronous or long-running communications, but without the requirement to implement polling patterns which many API providers find onerous to support.

Implementing Webhooks typically involves a registration step, which can be defined using regular Operations and allows API consumers to only consume the events they want to receive. GitHub provides a great example of an API provider who makes extensive use of Webhooks and the means to register for specification events.

API providers still need to define the shape of a given webhook, however. They can do this using the webhooks property which is found at the root of the OpenAPI document.

Webhooks are implemented at the root of the OpenAPI object

A webhook is, in fact, simply a Path Item Object and can support one or more Operation objects. The key difference is that Webhooks are not encapsulated by a Paths Object, as the API consumer registers (via an out-of-band mechanism) to receive the webhook at a URL of their choosing. Webhooks therefore describe a template, expressed as a Path Item, for API consumers to follow in how they implement the webhook and validate incoming events.

Our Tic Tac Toe example includes a webhook that communicates the status of the board. This is not linked to a specific Operation, but given asynchronous behaviors are supported it is implied that this may be received as a result of the API consumer receiving a 202 HTTP return code:

webhooks:
  markStatus:
    post:
      summary: Status of mark operation
      description: Provides the status of the mark operation on completion
      operationId: markOperationWebhook
      responses:
        "200":
          description: Mark operation has completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/status"

The timing and periodicity of events sent over a webhook are typically defined outside of the OAD and described in an API provider’s documentation. That said, OpenAPI provides a convenient mechanism for describing webhooks alongside the description of the APIs.

Summary

In this topic we’ve learned that:

• Webhooks are a style of API that facilitates bi-directional communication between API providers and API consumers.
• OpenAPI provides the means for API providers to describe their webhooks for API consumers to use as a template for implementation.
• Webhooks in an OAD use Path Items but are not allied to a specific path through a Paths object.