Webhook Definitions in OpenAPI 3.1

Webhooks in OpenAPI

Webhooks allow your API to push events to client-registered URLs instead of requiring clients to poll. OpenAPI 3.1 introduced a dedicated webhooks section, while OpenAPI 3.0 uses callbacks within path operations.

OpenAPI 3.1 Webhooks

openapi: "3.1.0"
webhooks:
  orderCreated:
    post:
      summary: Order created event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderEvent"
      responses:
        "200":
          description: Webhook received

  orderShipped:
    post:
      summary: Order shipped event
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShipmentEvent"
      responses:
        "200":
          description: Acknowledged

Event Payload Schema

components:
  schemas:
    WebhookEnvelope:
      type: object
      required:
        - id
        - type
        - timestamp
        - data
      properties:
        id:
          type: string
          format: uuid
          description: Unique event ID for idempotency
        type:
          type: string
          description: Event type identifier
        timestamp:
          type: string
          format: date-time
        data:
          type: object
          description: Event-specific payload

    OrderEvent:
      allOf:
        - $ref: "#/components/schemas/WebhookEnvelope"
        - type: object
          properties:
            type:
              enum: [order.created]
            data:
              type: object
              properties:
                order_id:
                  type: string
                total:
                  type: number
                currency:
                  type: string

OpenAPI 3.0 Callbacks

For 3.0 specs, use callbacks within operations:

paths:
  /webhooks/register:
    post:
      summary: Register a webhook URL
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
      callbacks:
        orderEvent:
          "{$request.body#/url}":
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/OrderEvent"
              responses:
                "200":
                  description: OK

Webhook Security Headers

Document webhook signature headers:

webhooks:
  payment:
    post:
      parameters:
        - name: X-Webhook-Signature
          in: header
          required: true
          schema:
            type: string
          description: HMAC-SHA256 signature of the request body
        - name: X-Webhook-Timestamp
          in: header
          required: true
          schema:
            type: string
          description: Unix timestamp of when the event was sent

Documenting Retry Policy

Use the description field for delivery behavior:

webhooks:
  payment:
    post:
      description: |
        Webhook delivery retries up to 5 times with exponential backoff.
        Schedule: 1min, 5min, 30min, 2hr, 24hr.
        Return 2xx to acknowledge. Non-2xx triggers retry.