openapi: 3.0.1
servers:
- url: https://api.bombora.com/webhooks/v1
info:
  title: Webhooks API
  description: 'The Webhooks API provides the ability to create webhook destinations for receiving various
    Bombora event subscriptions.


    ### Resource Structure

    The API revolves around the following resources:


    * **Destinations:** Represent webhook destinations that can receive event notifications.

    * **Events:** Represent event types that can be subscribed to for each destination.


    ### **Security**

    All API endpoints are secured with OAuth 2.0 bearer token authentication. Developers must include
    a valid Bearer token in the Authorization request header to access endpoints.

    Go to the [Get Started](/get-started) page for additional details.


    ### **Error Handling**

    The API returns appropriate HTTP status codes and error messages in case of unauthorized access (401
    Unauthorized) or forbidden actions (403 Forbidden), ensuring secure and reliable interaction.

    '
  version: 1.0.1
paths:
  /destinations:
    get:
      tags:
      - Destinations
      description: Returns list of webhook destinations.
      responses:
        '200':
          description: Success - The response body includes the requested resource.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DestinationSummary'
              example:
                destinations:
                - destinationId: ab5f2807-9483-4de4-a36d-8482c074e918
                  name: destination name
                  description: destination description
                - destinationId: 12345678-9483-4de4-a36d-101213141516
                  name: destination name
                  description: destination description
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      security:
      - bearerAuth: []
  /destination:
    post:
      tags:
      - Destinations
      description: Create a webhook destination that can be used with event type subscriptions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Destination'
              - $ref: '#/components/schemas/auth'
            example:
              name: Webhook Receiver
              description: This is where Bombora will send messages to
              address: https://api.bombora.com/api/webhook-receiver
              headers:
                X-Source: Bombora
              auth:
                secret: Some example $3cr3t! 1234
      responses:
        '200':
          description: Success - The request has been processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
              example:
                destinationId: ab5f2807-9483-4de4-a36d-8482c074e918
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
  /destination/{destinationId}:
    get:
      tags:
      - Destinations
      description: Retrieve the destination object (excluding “auth”).
      parameters:
      - $ref: '#/components/parameters/destinationId'
      responses:
        '200':
          description: Success - The response body includes the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Destination'
              example:
                destination:
                  name: Webhook Receiver
                  description: This is where Bombora will send messages to
                  address: https://api.bombora.com/api/webhook-receiver
                  headers:
                    X-Source: Bombora
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      security:
      - bearerAuth: []
    put:
      tags:
      - Destinations
      description: 'Replaces the destination document (excluding “auth” object).

        * To update the "auth" use the PUT ```/destination/{destinationId}/auth``` endpoint.

        '
      parameters:
      - $ref: '#/components/parameters/destinationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Destination'
            example:
              name: Webhook Receiver
              description: This is where Bombora will send messages to
              address: https://api.acmecorp.com/api/webhook-receiver
              headers:
                X-Source: Bombora
      responses:
        '200':
          description: Success - The request has been processed successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
    delete:
      tags:
      - Destinations
      description: Deletes the destination and all related subscriptions, if all events are disabled;
        otherwise, fails with a message indicating that events must be first disabled.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      responses:
        '200':
          description: Success - The resource no longer exists.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
      security:
      - bearerAuth: []
  /destination/{destinationId}/auth:
    put:
      tags:
      - Destinations
      description: Replaces the specified destination’s auth object.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth'
            example:
              auth:
                secret: Some example $3cr3t! 1234
      responses:
        '200':
          description: Success - The response body includes the requested resource.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
  /destination/{destinationId}/events:
    get:
      tags:
      - Events
      description: Returns list of subscribable events, along with a status.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      responses:
        '200':
          description: Success - The destinations were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    description: A list of subscribable events types and their current status.
                    items:
                      type: object
                      properties:
                        eventType:
                          type: string
                          description: Name of the event type.
                          example:
                            eventType: SignalDefinitionCreated
                        enabled:
                          description: True if event type is enabled, otherwise false.
                          type: boolean
                          example:
                            enabled: true
              example:
                events:
                - eventType: SignalDefinitionCreated
                  enabled: true
                - eventType: SignalDefinitionUpdated
                  enabled: false
                - eventType: SignalDefinitionDeleted
                  enabled: false
                - eventType: AccountListAccountsUpdated
                  enabled: true
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - bearerAuth: []
  /destination/{destinationId}/event/{eventType}:
    get:
      tags:
      - Events
      description: Retrieve the configuration and related stats for the specified event type.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      - $ref: '#/components/parameters/eventType'
      responses:
        '200':
          description: Success - The response body includes the requested resource.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Event'
                - $ref: '#/components/schemas/stats'
              examples:
                Example return for an event that has been subscribed to:
                  summary: Example return for an event that has been subscribed to.
                  value:
                    enabled: true
                    headers:
                      X-Message-Type: signal-is-ready
                    stats:
                      successful: 94
                      failed: 4
                      lastError: 401 Unauthorized
                      lastErrorAction: Retried
                      lastErrorTimestamp: '2023-09-05 15:22:04Z'
                Example an event with no subscriptions enabled:
                  summary: If event exists, but has never been subscribed to; or, subscription has been
                    deleted, endpoint returns.
                  value:
                    enabled: false
                    headers: {}
                    stats: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - bearerAuth: []
    put:
      tags:
      - Events
      description: Replaces the event document for the specified webhook destination.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      - $ref: '#/components/parameters/eventType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
            example:
              enabled: true
              headers:
                X-Message-Type: signal-is-ready
      responses:
        '200':
          description: Success - The request has been processed successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
    delete:
      tags:
      - Events
      description: Deletes the event from the subscription list.
      parameters:
      - $ref: '#/components/parameters/destinationId'
      - $ref: '#/components/parameters/eventType'
      responses:
        '200':
          description: The resource no longer exists.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  parameters:
    destinationId:
      name: destinationId
      in: path
      required: true
      description: An identifier for the destination.
      schema:
        type: string
        format: uuid
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    eventType:
      name: eventType
      in: path
      required: true
      schema:
        type: string
        example:
          SignalDefinitionCreated: null
  schemas:
    DestinationSummary:
      type: object
      properties:
        destinationId:
          type: string
          format: uuid
          description: The unique identifier (AccountListId) of the account list.
        name:
          description: The destination name.
          type: string
          example:
            name: Webhook Receiver
        description:
          description: The destination description.
          type: string
          example:
            description: This is where Bombora will send messages to
    Destination:
      type: object
      required:
      - name
      - address
      properties:
        name:
          description: Name of the destination.
          type: string
          example:
            name: Webhook Receiver
        description:
          description: Description of the destination.
          type: string
          example:
            description: This is where Bombora will send messages to
        address:
          description: The fully qualified url for events to be posted to.
          type: string
          format: uri
          example:
            address: https://api.bombora.com/api/webhook-receiver
        headers:
          type: object
          description: Expected headers to receive when webhook is triggered.
          example:
            headers:
              X-Source: Bombora
          additionalProperties:
            type: string
    auth:
      type: object
      description: Auth object containing data and/or credentials used in authenticating the connection
        back to the webhook address.
      properties:
        secret:
          description: When provided, this UTF-8 value will be used as the key to calculate a HMAC (Hash-based
            Message Authentication Code) using the SHA-256 hash function. The HMAC is computed on the
            UTF-8 HTTP response body, and will be sent in the X-Bombora-Signature-256 HTTP response header.
          type: string
    Event:
      type: object
      properties:
        enabled:
          description: True if event type is enabled; otherwise, false.
          type: boolean
        headers:
          type: object
          description: Expected headers to receive when event type is triggered.
          additionalProperties:
            type: string
    stats:
      type: object
      description: Stats related to the event type subscription.
      properties:
        successful:
          description: Count of successful posts of event to destination.
          type: integer
        failed:
          description: Count of failed posts of event to destination.
          type: integer
        lastError:
          description: Error message for last failed event post.
          type: string
        lastErrorAction:
          description: Action taken upon last failure of event post.
          type: string
        lastErrorTimestamp:
          description: Timestamp of last event post failure.
          type: string
    ErrorMessageResponse:
      type: object
      properties:
        message:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    UnauthorizedError:
      description: The access token is missing or invalid.
    ForbiddenError:
      description: The access token does not have permission to access this API.
    BadRequestError:
      description: The request is syntactically invalid.
    NotFoundError:
      description: The resource could at this path does not exist.
    ConflictError:
      description: Resource could not be retrieved due to a conflict with the current state of the resource
        (pending update or currently in use).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
    UnprocessableEntityError:
      description: The request body is syntactically correct but semantically incorrect, such as validation
        errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
security:
- bearerAuth: []