Recommended Free Tools
Define independent incoming webhooks in the root-level webhooks field of an OpenAPI 3.1-or-later document. Each entry describes a request with a Path Item Object (or a reference), including its payload and expected response. Whether those definitions appear correctly in generated API documentation depends on the specific generator, renderer, schema version, and configuration; the schema alone cannot guarantee the final layout.
Where webhooks belong in OpenAPI
The OpenAPI Specification v3.2.1 defines webhooks as a map of names to Path Item Objects or Reference Objects. These represent incoming requests that the API provider may send independently and that an API consumer may choose to implement. OpenAPI 3.1 introduced this root-level field.
A webhook is different from a normal endpoint: the provider initiates the HTTP request, rather than the consumer calling an operation to obtain a result. Registration may still happen through a dashboard, provisioning API, contract, or another out-of-band process; the OpenAPI document describes the request contract, not necessarily how a consumer subscribes.
Minimal schema shape
openapi: 3.1.0
info:
title: Billing API
version: 1.0.0
webhooks:
invoice.paid:
post:
summary: Invoice-paid event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvoicePaid'
responses:
'2XX':
description: Event accepted
components:
schemas:
InvoicePaid:
type: object
required: [invoiceId, paidAt]
properties:
invoiceId:
type: string
paidAt:
type: string
format: date-timeThe webhook name, operation description, request body, schemas, headers, security requirements, and responses give a documentation tool the material it can present to readers. Use a Reference Object when the Path Item is defined elsewhere in the document.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
Webhook versus callback
| Question | Root-level webhook | Callback |
|---|---|---|
| What starts the request? | The provider sends it independently of another operation. | It is associated with a parent operation and is part of that operation’s interaction. |
| Where is it declared? | At the document root in webhooks. |
Inside an operation, under its callback definition. |
| Typical use | Events such as invoice.paid that a consumer may implement. |
A consumer supplies a callback URL and the server calls it as a consequence of an API operation. |
| What the schema describes | The incoming request contract and expected response. | The callback interaction tied to the parent operation. |
Do not model an independent event as a callback merely because both involve provider-to-consumer HTTP traffic. The relationship to a parent operation determines which construct communicates the intent.
What generated documentation can show
Documentation generators can read OpenAPI descriptions and expose webhook operations, payload schemas, and responses. For example, the OpenAPI Generator documentation lists its openapi generator as type DOCUMENTATION, identifies Mustache as the default templating engine, and says that it creates a static openapi.json file. Those facts describe that generator’s documented metadata; they do not establish that every renderer displays every OpenAPI 3.1 or 3.2 webhook field.
Why output varies
- The schema may use a version the tool does not fully support.
- The generator may preserve webhook definitions while the selected renderer omits or hides them.
- Templates can choose different labels, navigation locations, or response displays.
- References, discriminators, security declarations, and vendor extensions may render differently from inline definitions.
- Build configuration may select a different input file, template set, or generator version than the one you inspected.
Therefore, “the tool accepts OpenAPI” is not proof that your published site will contain usable webhook pages. Validate the actual generated output from the exact schema, tool version, renderer, and configuration used by your build.
Rank #2
Document delivery behavior outside the schema
An OpenAPI webhook definition is primarily a contract for the HTTP request and response. It does not, by itself, explain when an event is emitted or how often it is sent. The OpenAPI Initiative’s learning material states: “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.”
Keep operational guidance in the provider’s webhook documentation, then reference the relevant event name and schema. Depending on the provider, that separate material may need to cover:
- What business event causes delivery and whether one event can be emitted more than once.
- Subscription or registration steps, required permissions, and how endpoints are changed or removed.
- Authentication, signature verification, required headers, and replay protection.
- Timeout expectations and the response status that means “accepted.”
- Ordering, delivery delays, and whether events can arrive after related API state changes.
- Retry, backoff, expiration, and dead-letter behavior, but only where the provider has defined those rules.
- Payload versioning, deprecation policy, and sample events.
Do not imply a retry schedule, delivery guarantee, or periodic interval unless the provider has documented it. The OpenAPI schema cannot fill those operational gaps automatically.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical workflow for reliable webhook docs
- Set the document version. Use OpenAPI 3.1 or later when you need the root-level
webhooksfield. Confirm that the validator and downstream tools accept that version. - Add one named entry per independent event. Under
webhooks, define a Path Item or a reference. Keep names stable and meaningful to readers. - Describe the operation completely. Add a summary and description, request body media type, required fields, reusable schemas, relevant headers, security information, and realistic success and error responses.
- Write the operational page separately. Explain registration, timing, authentication, verification, idempotency expectations, and delivery behavior in provider documentation.
- Generate with the production toolchain. Use the same schema file, generator version, renderer, templates, and configuration that publish your docs.
- Inspect the result. Check navigation, webhook names, payload properties, examples, response codes, references, and links. Confirm that a reader can distinguish provider-initiated events from callable API operations.
- Validate changes in CI. Fail the build on an invalid OpenAPI document, and add an output check or review step for the webhook pages your renderer is expected to produce.
What you can and cannot conclude without testing
You can conclude from a valid OpenAPI 3.1-or-later schema that the webhook contract is represented in a standard location. You cannot conclude that a particular project’s generated documentation displays it, because that outcome depends on the implementation details of the chosen generator and renderer. Without the actual schema, tool version, templates, and configuration, the behavior of a specific project remains unknown.
The Bottom Line
Use the root-level webhooks field for independent provider-initiated events, use callbacks only when the interaction belongs to a parent operation, and document timing and delivery rules separately. Treat generated pages as an output to validate—not as a guaranteed consequence of adding the schema field.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
