openapi: 3.0.3
info:
  title: Register to Webhook Events API
  version: 1.1.0
  description: >
    The Webhook APIs is a REST API designed to manage webhooks for booking
    notifications. It allows partners to register, update, and delete webhook
    endpoints, enabling them  to receive real-time booking event updates.
  contact:
    name: Bookable
    url: https://www.bookabletech.com
    email: hello@bookabletech.com
servers:
  - url: https://api-staging.bookabletech.com
    description: Staging
  - url: https://api.bookabletech.com
    description: Production
tags:
  - name: webhook
    description: Operations related to webhook management
paths:
  /webhooks:
    post:
      summary: Register a webhook endpoint for booking notifications
      operationId: RegisterWebhook
      tags:
        - webhook
      requestBody:
        description: Webhook registration request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegistrationRequest'
      responses:
        '200':
          description: Webhook successfully registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegistrationResponse'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - Staging: []
        - Production: []
    put:
      summary: Update the webhook callback URL of the specific distributor logged
      operationId: UpdateWebhook
      tags:
        - webhook
      requestBody:
        description: Webhook update request. Only the `callbackUrl` can be modified.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegistrationRequest'
      responses:
        '204':
          description: Webhook successfully updated
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging: []
        - Production: []
    delete:
      summary: Delete the webhook for a specific distributor
      operationId: DeleteWebhook
      tags:
        - webhook
      responses:
        '204':
          description: Webhook successfully deleted
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging: []
        - Production: []
  /webhooks/test:
    post:
      summary: Trigger a test webhook event
      operationId: TriggerTestWebhook
      tags:
        - webhook
      description: >
        Sends a test webhook notification to the registered callback URL. This
        endpoint is useful for testing webhook integration and verifying that
        the partner's endpoint can receive and process webhook events correctly.
      responses:
        '202':
          description: Test webhook event accepted and queued for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestWebhookResponse'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - Staging: []
        - Production: []
components:
  schemas:
    WebhookRegistrationRequest:
      type: object
      required:
        - callbackUrl
      properties:
        callbackUrl:
          type: string
          format: uri
          description: HTTPS URL to be called when a booking event occurs
          example: https://partner.example.com/webhooks/bookings
          nullable: false
    WebhookRegistrationResponse:
      type: object
      properties:
        secretKey:
          type: string
          description: Unique secret key for the registered webhook to verify data
          example: 123e4567-e89b-12d3-a456-426655440000
        callbackUrl:
          type: string
          format: uri
          description: HTTPS URL to be called when a booking event occurs
          example: https://partner.example.com/webhooks/bookings
    TestWebhookResponse:
      type: object
      properties:
        message:
          type: string
          description: Confirmation message
          example: Test webhook event has been queued for delivery
        eventId:
          type: string
          description: Unique identifier for the test event
          example: evt_test_123e4567
  securitySchemes:
    Staging:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://bookabletech.uk.auth0.com/oauth/token
      description: |
        This API uses OAuth2 client credentials flow via Auth0.
        **Important:** Include the `audience` parameter in your token request.
        Example token request:
        ```
        POST https://bookabletech.uk.auth0.com/oauth/token
        {
          "grant_type": "client_credentials",
          "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET",
          "audience": "api.bookabletech.com"
        }
        ```
    Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.bookabletech.com/oauth/token
      description: |
        This API uses OAuth2 client credentials flow via Auth0.
        **Important:** Include the `audience` parameter in your token request.
        Example token request:
        ```
        POST https://auth.bookabletech.com/oauth/token
        {
          "grant_type": "client_credentials",
          "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET",
          "audience": "api.bookabletech.com"
        }
        ```
  responses:
    ClientError:
      description: Client error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri
                description: >-
                  A URI reference [rfc9457] that identifies the problem type.
                  This specification encourages that, when dereferenced, it
                  provides human-readable documentation for the problem type
                  (e.g., using HTML [W3C.REC-html5-20141028]). When this member
                  is not present, its value is assumed to be "about:blank".
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem type. It SHOULD
                  NOT change from occurrence to occurrence of the problem,
                  except for purposes of localization.
              status:
                type: integer
                format: int32
                description: >-
                  The HTTP status code [rfc9457, Section 3.1.12] generated by
                  the origin server for this occurrence of the problem.
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
              instance:
                type: string
                format: uri
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem. It may or may not yield further information if
                  dereferenced.
            required:
              - title
              - status
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri
                description: >-
                  A URI reference [rfc9457] that identifies the problem type.
                  This specification encourages that, when dereferenced, it
                  provides human-readable documentation for the problem type
                  (e.g., using HTML [W3C.REC-html5-20141028]). When this member
                  is not present, its value is assumed to be "about:blank".
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem type. It SHOULD
                  NOT change from occurrence to occurrence of the problem,
                  except for purposes of localization.
              status:
                type: integer
                format: int32
                description: >-
                  The HTTP status code [rfc9457, Section 3.1.12] generated by
                  the origin server for this occurrence of the problem.
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
              instance:
                type: string
                format: uri
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem. It may or may not yield further information if
                  dereferenced.
            required:
              - title
              - status
