[ADP-760] OpenAPI: Webhooks

Guidance

• MUST use OpenAPI 3.1.0 or later for defining webhooks
• MUST use the webhooks section in the OpenAPI document to define webhooks
• SHOULD provide a clear description for each webhook, including its purpose and when it's triggered
• SHOULD define the expected payload structure for each webhook
• SHOULD specify any authentication requirements for webhook endpoints
• SHOULD include example payloads for each webhook
• SHOULD use appropriate HTTP status codes for webhook responses
• MAY include rate limiting information for webhooks

Example

openapi: 3.1.0
info:
  title: Webhook Example
  version: 1.0.0

webhooks:
  newPet:
    post:
      summary: Information about a new pet
      description: Webhook triggered when a new pet is added to the system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPetPayload'
      responses:
        '200':
          description: Webhook received successfully
        '401':
          description: Unauthorized
        '429':
          description: Too many requests

components:
  schemas:
    NewPetPayload:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: The pet's unique identifier
        name:
          type: string
          description: The name given to the pet
        tag:
          type: string
          description: The tag assigned to the pet

  securitySchemes:
    webhookAuth:
      type: http
      scheme: bearer

Related ADPs

• [ADP-601] Events as Part of API Design
• [ADP-607] Event Tracing
• [ADP-42] API Lifecycle Management

References

• OpenAPI Specification - Webhooks Object
• Bump.sh Blog: Documenting your OpenAPI webhooks
• GEFEG: Create your flexible APIs now with OpenAPI 3.1 and GEFEG.FX