Skip to main content

Webhooks

One of the greatest new features provided by OpenAPI 3.1 is the support of webhooks. Indeed, a OpenAPI 3.1 documentation may include paths and / or webhooks, when paths were required for previous version.

Every webhook has a required keyName, and some operations. If we follow this example, provided for OpenAPI 3.1 by OpenAPI Initiative:

webhooks:
  # Each webhook needs a name
  newPet:
    # This is a Path Item Object, the only difference is that the request is initiated by the API provider
    post:
      description: A new pet arrived, let's come and discover it IRL.
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

Here, there is a single webhook whom keyName is newPet , and a POST operation. If such a documentation was generated by Bump (see live documentation):

Example webhook rendering

  • Webhook's name is deduced from the keyName.
  • Webhook's operation name is extracted from field summary.
  • As for endpoints, webhook has body parameters, responses... and some curl and request payloadexamples are generated.

Furthermore, webhooks are fully compatible with UI customization How to group operations?

By adding some tags to your webhooks, you can re-organize how webhooks are named, sorted, and how webhooks operations are sorted.