[ADP-760] OpenAPI: Webhooks

Overview

Webhooks are a widely-used pattern for delivering notifications between applications via HTTP endpoints. This specification provides guidelines for implementing webhooks in OpenAPI, incorporating best practices from the CloudEvents specification.

Guidance

Security Requirements

• MUST use HTTPS (HTTP-over-TLS) for all webhook connections
• MUST implement one of these authorization methods:
  • Bearer token in Authorization header
  • Basic authentication
  • Signature based authentication
• MUST NOT use challenge-based authentication schemes
• SHOULD implement abuse protection mechanisms:
  • Validation handshake during subscription
  • Rate limiting with Retry-After header
  • Origin validation using WebHook-Request-Origin header

Webhook Definition

• MUST use OpenAPI 3.1.0 or later for defining webhooks
• MUST use the webhooks section in the OpenAPI document
• MUST use POST method for webhook deliveries
• MUST include Content-Type header and payload (empty payloads not allowed)
• MUST NOT follow HTTP redirects (3xx responses)

Response Handling

• MUST handle these status codes appropriately:
  • 200/201: Successfully processed with payload
  • 204: Successfully processed without payload
  • 202: Accepted but not yet processed
  • 410: Endpoint retired
  • 415: Unsupported media type
  • 429: Rate limit exceeded (with Retry-After header)

Documentation

• MUST document:
  • Authentication requirements and methods
  • Expected request/response payloads
  • Rate limiting policies
  • Required headers
• SHOULD include example payloads and responses
• SHOULD describe retry policies and error handling

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.
        - Requires HTTPS
        - Rate limited to 100 requests/minute
        - Includes WebHook-Request-Origin header for validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPetPayload'
      parameters:
        - in: header
          name: WebHook-Request-Origin
          required: true
          schema:
            type: string
          description: DNS name identifying the sending system
      responses:
        '200':
          description: Webhook processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '202':
          description: Webhook accepted, processing pending
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying

components:
  schemas:
    NewPetPayload:
      type: object
      required:
        - id
        - name
        - timestamp
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the pet
        name:
          type: string
          description: Pet's name
        timestamp:
          type: string
          format: date-time
          description: When the pet was created
    WebhookResponse:
      type: object
      properties:
        status:
          type: string
          enum: [success, partial, error]
        message:
          type: string

  securitySchemes:
    webhookAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token for webhook authentication.
        Token must be included in either:
        - Authorization header
        - 'token' query parameter

References

• OpenAPI Specification - Webhooks Object
• CloudEvents HTTP Webhook Specification
• RFC 6750: OAuth 2.0 Bearer Token Usage
• Webhook Authentcations

Changelog

• 2025-03-07: Updated with CloudEvents specification alignment and detailed security requirements.