OpenAPI 3.1のWebhook定義

OpenAPIでのWebhook

Webhookを使用すると、クライアントがポーリングする代わりに、APIが登録されたURLにイベントをプッシュできます。OpenAPI 3.1は専用の webhooks セクションを導入し、OpenAPI 3.0はパス操作内の callbacks を使用します。

OpenAPI 3.1 Webhooks

openapi: "3.1.0"
webhooks:
  orderCreated:
    post:
      summary: 注文作成イベント
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderEvent"
      responses:
        "200":
          description: Webhook受信

  orderShipped:
    post:
      summary: 注文出荷イベント
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShipmentEvent"
      responses:
        "200":
          description: 確認

Webhookセキュリティヘッダー

Webhook署名ヘッダーのドキュメント化：

webhooks:
  payment:
    post:
      parameters:
        - name: X-Webhook-Signature
          in: header
          required: true
          schema:
            type: string
          description: リクエストボディのHMAC-SHA256署名
        - name: X-Webhook-Timestamp
          in: header
          required: true
          schema:
            type: string
          description: イベント送信時のUnixタイムスタンプ

リトライポリシーのドキュメント化

配信動作にdescriptionフィールドを使用：

webhooks:
  payment:
    post:
      description: |
        Webhook配信は指数バックオフで最大5回リトライ。
        スケジュール：1分、5分、30分、2時間、24時間。
        確認には2xxを返す。2xx以外はリトライをトリガー。