# Webhooks, Callbacks, Links and File Uploads — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/d-advanced

> Describe outgoing requests, related operations and multipart 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.

```yaml
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.

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

- [ ] In the servers section
- [ ] In securitySchemes
- [x] In the top-level webhooks section
- [ ] They cannot be described

*Answer:* In the top-level webhooks section. OpenAPI 3.1 added a top-level webhooks object for outgoing event requests.