Webhooks are available with OpenAPI 3.1, and they are already fully supported by Bump. Here is how you should add these webhooks to your documentation.

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:

# Each webhook needs a name
# This is a Path Item Object, the only difference is that the request is initiated by the API provider
description: A new pet arrived, let's come and discover it IRL.
description: Information about a new pet in the system
$ref: "#/components/schemas/Pet"
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):

  • 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.