What are OpenAPI webhooks and how are they defined?

What are OpenAPI webhooks and how are they defined? #

Webhooks are one of the most widely used patterns in modern APIs — enabling services to push data to client-registered URLs in real time rather than requiring clients to poll for updates. With the release of OpenAPI 3.1, the specification gained a dedicated, first-class mechanism for describing webhooks: the top-level webhooks object. This addition allows API providers to formally document the events their services emit, giving consumers the same schema-level clarity for incoming webhook payloads that OpenAPI has always provided for outbound API calls.

What is a Webhook? #

A webhook is an HTTP callback — a POST request that a server sends to a URL provided by a client when a particular event occurs. Unlike traditional REST API calls (where the client initiates the request), webhooks reverse the flow: the server is the sender, and the client must expose an endpoint to receive the payload.

Webhooks are used extensively by platforms like:

  • Stripe — for payment, subscription, and fraud events.
  • GitHub — for repository, PR, and CI/CD events.
  • Shopify — for order, product, and customer events.
  • Twilio — for inbound messages and call status updates.
  • SendGrid — for email delivery and engagement events.

Without a standardized way to describe webhook payloads, API consumers had to rely on prose documentation and hope it matched the actual events sent in production.

Webhooks Before OpenAPI 3.1 #

OpenAPI 3.0 had no native webhook concept. API designers used the callbacks feature to describe outgoing HTTP calls triggered by a specific API request, which partially addressed webhooks tied to a subscription operation. However, standalone webhooks — events fired asynchronously by the server based on internal state changes — could not be described natively.

Workarounds included:

  • Documenting webhook payloads as generic schema components with no binding to an event trigger.
  • Using the x-webhooks extension (a community convention) to attach webhook descriptions to the document.
  • Maintaining separate documentation files outside the OpenAPI document.

All of these approaches lacked standardization and tool support.

The webhooks Object in OpenAPI 3.1 #

OpenAPI 3.1 introduces a top-level webhooks field alongside paths, components, and info. Its value is a map of webhook names to Path Item Objects — the same structure used to describe API endpoints, enabling full reuse of the existing OpenAPI operation model.

openapi: 3.1.0
info:
  title: Order Management API
  version: 1.0.0
webhooks:
  newOrder:
    post:
      summary: New order placed
      description: >
        Sent when a customer successfully places an order. The receiving
        endpoint must respond with HTTP 200 within 5 seconds.        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEvent'
      responses:
        "200":
          description: Webhook received successfully
        "400":
          description: Invalid payload

Here, newOrder is the name of the webhook. The post operation describes the HTTP method the server will use to send the event, the requestBody describes the payload schema, and the responses describe what the server expects the client endpoint to return.

Reusing the Path Item Object Model #

Because webhooks in OpenAPI 3.1 use the same Path Item Object structure as API paths, all existing OpenAPI conventions apply:

  • parameters — describe query or header parameters included in the webhook request (e.g., a signature header).
  • requestBody — the event payload, fully schema-described with all the richness of OpenAPI schemas.
  • responses — the expected HTTP response from the receiving endpoint.
  • security — the security schemes that apply (e.g., an HMAC signature header for verifying authenticity).
  • $ref — webhook definitions can reference shared components, keeping the document DRY.

Describing Multiple Event Types #

An API commonly emits multiple event types. Each is a separate entry in the webhooks map:

webhooks:
  orderPlaced:
    post:
      summary: A new order was placed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPlacedEvent'
      responses:
        "200":
          description: OK

  orderShipped:
    post:
      summary: An order was shipped
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderShippedEvent'
      responses:
        "200":
          description: OK

  orderCancelled:
    post:
      summary: An order was cancelled
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelledEvent'
      responses:
        "200":
          description: OK

Shared event envelope properties (e.g., event type, timestamp, event ID) can be extracted into a base schema and composed using allOf.

Webhook Security: Describing Signature Verification #

Most webhook providers sign their payloads with an HMAC signature delivered in a request header (e.g., X-Signature-256). This allows receivers to verify that the event came from the legitimate sender. OpenAPI 3.1 allows documenting this pattern:

webhooks:
  newOrder:
    post:
      parameters:
        - name: X-Signature-256
          in: header
          required: true
          schema:
            type: string
          description: >
            HMAC SHA-256 signature of the request body, computed using your
            webhook signing secret. Verify this before processing the event.            
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEvent'
      responses:
        "200":
          description: OK

Webhooks vs. Callbacks in OpenAPI #

It is important to distinguish webhooks from callbacks:

  • Callbacks are outgoing HTTP calls made by the server in response to a specific API request — for example, calling a URL that the client provided in the original request body. They are defined inside an operation object.
  • Webhooks are autonomous server-initiated events not tied to any specific preceding API call. They are defined at the document’s top level.

Both mechanisms model push-style HTTP, but they serve different integration patterns.

Tooling Support for Webhooks #

Several OpenAPI tools now support the webhooks field:

  • Redoc — renders webhook sections in generated documentation, clearly distinguishing them from API paths.
  • Stoplight Studio — the visual editor allows adding and editing webhooks as first-class document elements.
  • Redocly CLI — bundles, lints, and validates documents including webhook definitions.
  • openapi-generator — work is ongoing to generate webhook handler stubs in server-side generated code.
  • Spectral — custom rulesets can enforce conventions on webhook definitions.

Best Practices for Defining OpenAPI Webhooks #

  1. Give each webhook a clear, event-oriented name — use names like orderPlaced, userCreated, or paymentFailed that reflect the domain event, not generic names like webhook1.
  2. Fully describe the payload schema — include every field with type, description, and example. This is the primary value of the webhook definition for consumers.
  3. Document the expected response — specify what HTTP status codes the server expects and what happens if the client fails to respond in time (e.g., retry behavior).
  4. Include signature verification headers — describe any authentication or integrity headers in the parameters section.
  5. Use $ref for shared event components — a common event envelope schema (with eventId, eventType, timestamp) should live in components/schemas and be composed into each event type.

Conclusion #

The webhooks field introduced in OpenAPI 3.1 fills a long-standing gap in the specification, enabling API providers to formally describe asynchronous server-initiated events alongside their REST API operations. By reusing the familiar Path Item Object model, webhooks benefit from the full expressive power of OpenAPI schemas, parameters, and security definitions. For teams building event-driven integrations — from payment platforms to e-commerce to IoT — standardized webhook documentation reduces integration guesswork and improves the developer experience for API consumers.

Last updated on April 29, 2026.

This website is not affiliated with the OpenAPI Initiative.