Webhooks, callbacks, links and 3.2 additions

Event-driven and hypermedia-style APIs need more than request/response paths.

OpenAPI can describe requests that your API sends:

Webhooks (3.1+, top-level webhooks): named events your API POSTs to URLs that subscribers registered out of band. Each is a Path Item describing the request you send and the responses you expect.
Callbacks: tied to a specific operation; the callback URL comes from the request at runtime via a runtime expression such as '{$request.body#/callbackUrl}'.

Links describe how a response value feeds another operation: after createBook returns id, the GetBook link says bookId: $response.body#/id. Tools can use links for navigation and test generation.

OpenAPI 3.2 (September 2025) is backwards compatible with 3.1 and adds:

Tags with summary, parent and kind for hierarchical navigation (replacing the x-tagGroups extension).
The QUERY HTTP method, additionalOperations for other methods, and an in: querystring parameter for a whole query string described by one schema.
Streaming and sequential media types (text/event-stream, application/jsonl, application/json-seq) with itemSchema describing each item.
OAuth 2.0 device authorization flow, oauth2MetadataUrl, deprecating security schemes, and defaultMapping for discriminators.

Tool support for 3.2 is still catching up, so check your generators and validators before upgrading.

For purely asynchronous, broker-based APIs (Kafka, MQTT), the sibling AsyncAPI specification is the better fit.

Example

openapi: 3.1.1
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders:
    post:
      operationId: createOrder
      responses:
        '201':
          description: Created
          links:
            GetOrder:
              operationId: getOrder
              parameters: { orderId: '$response.body#/id' }
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
      responses: { '200': { description: The order } }
webhooks:
  orderShipped:                 # we POST this to subscriber URLs
    post:
      requestBody:
        content: { application/json: { schema: { type: object, properties: { orderId: { type: string } } } } }
      responses: { '2XX': { description: Subscriber accepted the event } }

Remember

Webhooks: events you send to registered URLs (3.1+)
Callbacks: per-operation, URL taken from the request at runtime
Links map response values to other operations' parameters
3.2 adds hierarchical tags, QUERY, streaming itemSchema

Watch out for

Describing webhooks as normal paths, which tells clients they can call them.

Check yourself

How does a callback differ from a webhook?

Official docs: learn.openapis.org/specification/webhooks.html

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks