HTTP WebHook Specification - OpenAPI

components.yaml

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    CloudEventType:
      properties:
        eventType:
          type: string
        eventTypeVersion:
          type: string
        source:
          type: string
          format: uri
      required:
        - eventType
        - eventTypeVersion
        - source
  pathItems:
    CallbackOptions:
      options:
        security:
          - BearerAuth
        parameters:
          - name: WebHook-Request-Origin
            in: header
            required: true
            schema:
              type: string
              format: hostname
            example: eventsource.example.com
          - name: WebHook-Request-Callback
            in: header
            description: Callback URL using which abuse protection handshake can be confirmed asynchronously
            example: https://eventemitter.example.com/hooks/confirm?id=12345&key=...base64...
          - name: WebHook-Request-Rate
            in: header
            description: asks for permission to send notifications from this sender at the specified rate expressed in "requests per minute"
            schema:
              type: integer
              minimum: 1
            example: 120
        responses:
          '200':
            # TODO
    CallbackPost:
      post:
        security:
          - BearerAuth
        parameters:
          - name: access_token
            in: query
            schema:
              type: string
          - name: CE-CloudEventsVersion
            in: header
            required: true
            schema:
              type: string
            example: "0.1"
          - name: CE-EventType
            in: header
            required: true
            schema:
              type: string
              format: domain
            example: "com.example.someevent"
          - name: CE-EventTime
            in: header
            required: true
            schema:
              type: string
              format: date-time
            example: "2018-04-05T03:56:24Z"
          - name: CE-EventID
            in: header
            required: true
            schema:
              type: string
            example: "1234-1234-1234"
          - name: CE-Source
            in: header
            required: true
            schema:
              type: string
              format: uri
            example: "https://example.com/mycontext/subcontext"
        requestBody:
          required: false
          content:
            # TODO Any?
        responses:
          '200':
            description: Delivery has been accepted and processed, but response carries a payload
          '201':
            description: Delivery has been accepted and processed, but response carries no payload
          '202':
            description: Delivery has been accepted, but has not yet been processed or processing status is unknown
          '204':
            description: Delivery has been accepted and processed, but response carries no payload
          '410':
            description: Delivery target has been retired, sender SHOULD refrain from sending any further notifications
          '415':
            description: Delivery cannot be accepted because the notification format has not been understood
          '429':
            description: Delivery target is unable to process the request due to exceeding a request rate limit
            headers:
              Retry-After:
                schema:
                  oneOf:
                    - title: number of seconds
                      type: integer
                      description: The number of seconds the sender MUST refrein from sending further requests
                    - title: date-time
                      type: string
                      format: date-time
                      description: The UTC date/time until the sender MUST refrain from sending further requests

example-consumer.yaml

openapi: 3.0.0
info:
  version: 0.0.0
  title: Event consumer API
servers:
  - url: https://eventconsumer.example.com
paths:
  /hook:
    $ref: "components.yaml#/components/pathItems/CallbackOptions"
    $ref: "components.yaml#/components/pathItems/CallbackPost"

example-emitter.yaml

openapi: 3.0.0
info:
  version: 0.0.0
  title: Event source API
servers:
  - url: https://eventemitter.example.com
paths:
  /hooks:
    post:
      summary: Subscribe to a webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
                  pattern: '^https:\/\/*$'
                  example: https://eventconsumer.example.com/hook
                events:
                  type: array
                  items:
                    $ref: "components.yaml#/components/schemas/CloudEventType"
              required:
                - callbackUrl
      responses:
        '201':
          description: Webhook created
      callbacks:
        onEvent:
          '{$request.body#/callbackUrl}':
            $ref: "components.yaml#/components/pathItems/CallbackPost"
  /hooks/confirm:
    post:
      summary: Async abuse protection handshake confirmation
      parameters:
        - name: WebHook-Allowed-Origin
          in: header
          required: true
          schema:
            type: string
            format: hostname
          example: eventemitter.example.com
        - name: WebHook-Allowed-Rate
          in: header
          description: allows sender to send notifications at the specified rate expressed in "requests per minute"
          schema:
            type: integer
            minimum: 1
          example: 120
        - name: id
          in: query
          description: webhook id
          schema:
            type: string
        - name: key
          in: query
          description: webhook abuse protection handshake request key
          schema:
            type: string