Webhooks were added to the OpenAPI specification in version 3.1. The x-webhooks extension means you can add webhooks to your older OpenAPI version 3.0 or 2.0 descriptions.
For APIs that include webhooks, developer experience is improved by including them in the main API reference documentation.
OpenAPI 3.0 and older only
For OpenAPI 3.1 and later, use the built-in webhooks section. The x-webhooks structure is identical, to make your upgrade path easier.
The x-webhooks extension is used at the top level of an OpenAPI description.
| Option | Type | Description |
|---|---|---|
| x-webhooks | [ Path Item Object ] | A list of standard Path Item objects as described in the OpenAPI specification. |
The following example shows a snippet of an OpenAPI 3.0 description with a webhook.
openapi: 3.0.3
x-webhooks:
publishNewEvent:
post:
summary: New special event added
description: Publish details of a new or updated event.
operationId: publishNewEvent
tags:
- Events
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SpecialEvent"
type: object
properties:
eventId:
$ref: '#/components/schemas/EventId'
name:
$ref: '#/components/schemas/EventName'
location:
$ref: '#/components/schemas/EventLocation'
eventDescription:
$ref: '#/components/schemas/EventDescription'
dates:
$ref: '#/components/schemas/EventDates'
price:
$ref: '#/components/schemas/EventPrice'
required:
- name
- location
- eventDescription
- dates
- price
examples:
default_example:
summary: New special event
value:
eventId: 6744a0da-4121-49cd-8479-f8cc20526495
name: Time Traveler Tea Party
location: Temporal Tearoom
eventDescription: Sip tea with important historical figures.
dates:
- '2024-11-18'
- '2024-11-25'
- '2024-12-02'
price: 60
responses:
"202":
description: Data accepted.
The webhook is included alongside the other Operations with the same tag in the Redoc API reference documentation.
- Document webhooks with OpenAPI - Learn best practices for documenting webhooks in OpenAPI specifications and API reference documentation
- Show extensions configuration - Control which extensions are included in your API reference documentation for optimal presentation
- OpenAPI configuration settings - Complete reference for all available OpenAPI configuration options and customization settings
- Supported OpenAPI extensions - Complete list of all OpenAPI extensions supported by Redocly for enhanced API documentation