Webhooks, Callbacks, Links and File Uploads

Beyond simple request-response

Some API behaviour involves requests from your API to clients. Webhooks (top-level in 3.1) describe events your API sends to URLs that consumers register out of band: for example an orderShipped webhook POSTing an event payload, with its schema and expected response, plus details such as signature headers (X-Signature) consumers must verify. Callbacks describe requests sent in response to a specific operation, where the client supplies the callback URL in the request (for example callbackUrl in a payment request), using runtime expressions such as {$request.body#/callbackUrl}. Links describe how values from one response feed another operation (the id returned by createOrder used as orderId in getOrder), helping documentation and HATEOAS-style navigation. File uploads use multipart/form-data request bodies, with binary parts described as type: string with contentMediaType (3.1) or format: binary (3.0), and an encoding object to set per-part content types.

A webhook, a link and a multipart upload

Outgoing events, related operations and file uploads in one document.

webhooks:
  orderShipped:
    post:
      summary: Sent when an order is shipped
      parameters:
        - name: X-Signature
          in: header
          required: true
          description: HMAC-SHA256 of the raw body using your webhook secret
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderShippedEvent' }
      responses:
        '2XX': { description: Event accepted; any other status triggers a retry }

paths:
  /orders:
    post:
      operationId: createOrder
      responses:
        '201':
          description: Created
          links:
            GetCreatedOrder:
              operationId: getOrder
              parameters:
                orderId: '$response.body#/id'
  /orders/{orderId}/attachments:
    post:
      operationId: uploadAttachment
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, contentMediaType: application/pdf }
                note: { type: string, maxLength: 200 }
      responses:
        '201': { description: Attachment stored }

Document webhook retries and signatures

Consumers need to know how to verify a webhook's signature, what response you expect, how often you retry and whether events can arrive more than once or out of order. Put it in the descriptions.

Quick check: In OpenAPI 3.1, where are events that your API sends to registered consumer URLs described?

• In the servers section
• In securitySchemes
• In the top-level webhooks section
• They cannot be described