Bridge Webhooks API

openapi: 3.0.2
info:
  title: Bridge API Keys Webhooks API
  description: APIs to move into, out of, and between any form of a dollar
  version: '1'
servers:
- url: https://api.bridge.xyz/v0
  description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      summary: Get all webhook endpoints
      description: Get the full list of active and disabled webhook endpoints configured on Bridge
      tags:
      - Webhooks
      responses:
        '200':
          description: List of webhook endpoints (the returned list is empty if none found)
          content:
            application/json:
              schema:
                title: Webhooks
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/Webhook'
              examples:
                WebhooksFound:
                  summary: A non-empty list of webhook endpoints
                  value:
                    data:
                    - $ref: '#/components/examples/SuccessfulWebhookResponse'
                    - $ref: '#/components/examples/SuccessfulWebhookResponse2'
                NoWebhooksFound:
                  summary: An empty list of webhook endpoints
                  value:
                    data: []
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    post:
      summary: Create a webhook endpoint
      description: Create a new webhook endpoint to receive events from Bridge. Webhook endpoints begin in a disabled state and can be enabled with a PUT request. A maximum of 5 webhooks can be active or disabled at one time. Webhook endpoints can be created in Sandbox, but no webhook events will be sent.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      requestBody:
        description: Information about the webhook endpoint to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhook'
      responses:
        '201':
          description: Webhook endpoint created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              examples:
                SuccessfulWebhookCreateResponse:
                  summary: Webhook created
                  $ref: '#/components/examples/SuccessfulWebhookCreateResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /webhooks/{webhookID}:
    parameters:
    - $ref: '#/components/parameters/WebhookIDParameter'
    put:
      summary: Update a webhook
      description: Update the specified webhook object
      tags:
      - Webhooks
      requestBody:
        description: Updated webhook endpoint object
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutWebhookPayload'
      responses:
        '200':
          description: Successful webhook object response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              examples:
                SuccessfulWebhookResponse:
                  $ref: '#/components/examples/SuccessfulWebhookUpdateResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    delete:
      summary: Delete a webhook
      tags:
      - Webhooks
      description: Delete the specified webhook object. This webhook will no longer be accessible via API.
      responses:
        '200':
          description: Successfully deleted webhook response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              examples:
                DeletedCustomerResponse:
                  $ref: '#/components/examples/SuccessfulWebhookDeleteResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /webhooks/{webhookID}/events:
    parameters:
    - $ref: '#/components/parameters/WebhookIDParameter'
    get:
      summary: List upcoming events
      description: List the next 10 events that will be delivered to the specified webhook.
      tags:
      - Webhooks
      responses:
        '200':
          description: List of events (the returned list is empty if none found)
          content:
            application/json:
              schema:
                title: Webhook Events
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/WebhookEvent'
              examples:
                WebhookEventsFound:
                  summary: A non-empty list of webhook events
                  value:
                    data:
                    - $ref: '#/components/examples/SuccessfulWebhookEventsResponse'
                NoWebhooksFound:
                  summary: An empty list of webhook events
                  value:
                    data: []
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /webhooks/{webhookID}/logs:
    parameters:
    - $ref: '#/components/parameters/WebhookIDParameter'
    get:
      summary: View logs
      description: Display the most recent logs for deliveries to the specified webhook.
      tags:
      - Webhooks
      responses:
        '200':
          description: Recent delivery looks for the webhook (the returned list is empty if none found)
          content:
            application/json:
              schema:
                title: Delivery Logs
                type: object
                required:
                - count
                - data
                properties:
                  count:
                    type: integer
                    description: The number of logs returned
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/WebhookEventDeliveryLog'
              examples:
                WebhookEventsFound:
                  summary: A non-empty list of webhook events
                  value:
                    count: 1
                    data:
                    - $ref: '#/components/examples/SuccessfulWebhookLogsResponse/value'
                NoWebhookEventsFound:
                  summary: An empty list of webhook events
                  value:
                    data: []
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /webhooks/{webhookID}/send:
    parameters:
    - $ref: '#/components/parameters/WebhookIDParameter'
    - $ref: '#/components/parameters/IdempotencyKeyParameter'
    post:
      summary: Send event
      description: Send an event to the specified webhook endpoint. This will not effect other events in the delivery queue. This operation is possible for both active and disabled webhook endpoints.
      tags:
      - Webhooks
      requestBody:
        description: Specify the event to send to your endpoint.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendWebhookPayload'
      responses:
        '200':
          description: Event sent successfully
          content:
            application/json:
              schema:
                title: Webhook Event Sent
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    description: Message indicating the status of the request
              examples:
                WebhookEventSendSuccessResponse:
                  $ref: '#/components/examples/WebhookEventSendSuccessResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /webhook_events:
    get:
      summary: List webhook events
      description: List all webhook events for your account. Events are ordered by their event_sequence in ascending order. Results are limited to the events created in last 90 days.
      tags:
      - Webhooks
      parameters:
      - name: starting_after
        in: query
        description: Cursor for forward pagination. Returns events after the specified event ID.
        required: false
        schema:
          type: string
        example: wh_123abc
      - name: ending_before
        in: query
        description: Cursor for backward pagination. Returns events before the specified event ID.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of events to return (1-500, default 100).
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      - name: category
        in: query
        description: Filter events by category.
        required: false
        schema:
          type: string
          enum:
          - customer
          - external_account
          - kyc_link
          - liquidation_address
          - liquidation_address.drain
          - static_memo.activity
          - transfer
          - virtual_account
          - virtual_account.activity
          - bridge_wallet.activity
          - shift4_base_deposit
          - indexed_deposit
          - card_account
          - posted_card_account_transaction
          - card_transaction
          - card_withdrawal
      responses:
        '200':
          description: List of webhook events
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - count
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEvent'
                  count:
                    type: integer
                    description: Number of webhook events returned in this response
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    AuthenticationError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            MissingTokenError:
              summary: No Api-Key header
              description: The header may be missing or misspelled.
              value:
                code: required
                location: header
                name: Api-Key
                message: Missing Api-Key header
            InvalidTokenError:
              summary: Invalid key in Api-Key header
              value:
                code: invalid
                location: header
                name: Api-Key
                message: Invalid Api-Key header
    NotFoundError:
      description: No resource found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            NotFoundErrorExample:
              summary: Invalid customer id
              value:
                code: Invalid
                message: Unknown customer id
    UnexpectedError:
      description: Unexpected error. User may try and send the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UnexpectedError:
              summary: An unexpected error
              value:
                errors:
                - code: unexpected
                  message: An expected error occurred, you may try again later
    BadRequestError:
      description: Request containing missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BadCustomerRequestErrorExample:
              summary: Bad customer request
              value:
                code: bad_customer_request
                message: fields missing from customer body.
                name: first_name,ssn
  parameters:
    IdempotencyKeyParameter:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
    WebhookIDParameter:
      name: webhookID
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
  examples:
    SuccessfulWebhookLogsResponse:
      value:
        data:
          type: array
          minItems: 0
          items:
          - status: 200
            event_id: wh_event_id_123
            response_body: '{"message":"OK"}'
            created_at: '2024-01-01T00:00:00.000Z'
          - status: 200
            event_id: wh_event_id_456
            response_body: '{"message":"OK"}'
            created_at: '2024-01-01T00:00:00.000Z'
    SuccessfulWebhookCreateResponse:
      summary: Successful webhook endpoint creation
      value:
        id: wep_123
        url: https://my_endpoint.xyz/hooks
        status: disabled
        public_key: '-----BEGIN PUBLIC KEY-----\nFJJ3hFnaPLmxxG4a5w0BAQEFAAOCAQ8AMIIBCgKCAQEAtYhc6PV2LOs/nqDRHi0B\nMKTsdMLHtg58a1NDxaYfw4IZJ3hpy1qIFUgt5X0HhCYZE0Y40MyLGIejPyitEjYw\ni9/aE+9F/PN+btqN7OK6cVuF9s/R9cZCtNc27UdTQXrUO5T8GXNAMmRr0KFh8yPv\nfIgpoZn5ZhnyRbZpDvrxHzLmcZJFAX8Ca+KZLzgGVybEqJtP6fKAT0zrrUS1z44s\nRDOLiXl543cRAmBnUyrT6cXiNz/PNbm4zRK5Nx7LGxBFrCWQCao4Yi8hrwWsnHxg\n0Tcy3UyZhAcgL6ydVJfLD5x58Ri4BN32WPBtgSSO6JxZZwCiX0d1BOgq7+eNgmzN\nJQIDAQAB\n-----END PUBLIC KEY-----\n'
        event_categories:
        - customer
        - liquidation_address
        - virtual_account
        - virtual_account.activity
        - card_account
        - card_transaction
        - card_withdrawal
        - posted_card_account_transaction
    WebhookEventSendSuccessResponse:
      summary: Successful webhook event send
      value:
        message: Successfully sent the webhook event. This does not guarantee immediate delivery to the endpoint.
    SuccessfulWebhookResponse:
      summary: A successful webhook endpoint object.
      value:
        id: wep_123
        url: https://my_endpoint.xyz/hooks
        status: active
        public_key: '-----BEGIN PUBLIC KEY-----\nFAKEhFnaPLmxxG4a5w0BAQEFAAOCAQ8AMIIBCgKCAQEAtYhc6PV2LOs/nqDRHi0B\nMKTsdMLHtg58a1NDxaYfw4IZJ3hpy1qIFUgt5X0HhCYZE0Y40MyLGIejPyitEjYw\ni9/aE+9F/PN+btqN7OK6cVuF9s/R9cZCtNc27UdTQXrUO5T8GXNAMmRr0KFh8yPv\nfIgpoZn5ZhnyRbZpDvrxHzLmcZJFAX8Ca+KZLzgGVybEqJtP6fKAT0zrrUS1z44s\nRDOLiXl543cRAmBnUyrT6cXiNz/PNbm4zRK5Nx7LGxBFrCWQCao4Yi8hrwWsnHxg\n0Tcy3UyZhAcgL6ydVJfLD5x58Ri4BN32WPBtgSSO6JxZZwCiX0d1BOgq7+eNgmzN\nJQIDAQAB\n-----END PUBLIC KEY-----\n'
    SuccessfulWebhookDeleteResponse:
      summary: Successful webhook endpoint delete
      value:
        id: wep_123
        url: https://my_deleted_endpoint.xyz/hooks
        status: deleted
        public_key: '-----BEGIN PUBLIC KEY-----\nFJJ3hFnaPLmxxG4a5w0BAQEFAAOCAQ8AMIIBCgKCAQEAtYhc6PV2LOs/nqDRHi0B\nMKTsdMLHtg58a1NDxaYfw4IZJ3hpy1qIFUgt5X0HhCYZE0Y40MyLGIejPyitEjYw\ni9/aE+9F/PN+btqN7OK6cVuF9s/R9cZCtNc27UdTQXrUO5T8GXNAMmRr0KFh8yPv\nfIgpoZn5ZhnyRbZpDvrxHzLmcZJFAX8Ca+KZLzgGVybEqJtP6fKAT0zrrUS1z44s\nRDOLiXl543cRAmBnUyrT6cXiNz/PNbm4zRK5Nx7LGxBFrCWQCao4Yi8hrwWsnHxg\n0Tcy3UyZhAcgL6ydVJfLD5x58Ri4BN32WPBtgSSO6JxZZwCiX0d1BOgq7+eNgmzN\nJQIDAQAB\n-----END PUBLIC KEY-----\n'
    SuccessfulWebhookEventsResponse:
      summary: A list of events for the webhook endpoint
      value:
        data:
          type: array
          minItems: 0
          items:
          - api_version: v0
            event_id: wh_tmneA3b1rTv1q4gkvmPU53n
            event_developer_id: 2d127766-02fa-44b0-9fc8-a67665dbf109
            event_sequence: 1
            event_category: transfer
            event_type: transfer.deleted
            event_object_id: cc598628-29ab-448e-851f-7aaffb1a1171
            event_object_status: null
            event_object:
              id: cc598628-29ab-448e-851f-7aaffb1a1171
              state: awaiting_funds
              amount: '50.0'
              source:
                currency: usdc
                from_address: '0xd48f4e51c2fcd1c8489eb1a64588b29b76ad0a3f'
                payment_rail: ethereum
              receipt:
                gas_fee: '0.0'
                exchange_fee: '0.0'
                final_amount: '50.0'
                developer_fee: '0.0'
                initial_amount: '50.0'
                subtotal_amount: '50.0'
                url: https://dashboard.bridge.xyz/transaction/00000000-0000-0000-0000-000000000000/receipt/00000000-0000-0000-0000-000000000000
              currency: usd
              created_at: '2024-05-02T17:48:19.366Z'
              updated_at: '2024-05-02T17:48:19.366Z'
              destination:
                currency: usd
                payment_rail: ach
                external_account_id: 24fd61e9-80b6-464a-b5ee-9f7a521cb1f0
              on_behalf_of: 474c32b3-f3d6-43e3-92ce-a7d4e07fa0a4
              developer_fee: '0.0'
              source_deposit_instructions:
                amount: '50.0'
                currency: usdc
                to_address: null
                from_address: '0xd48f4e51c2fcd1c8489eb1a64588b29b76ad0a3f'
                payment_rail: ethereum
            event_object_changes:
              state:
              - pending
              - canceled
              updated_at:
              - '2024-05-02T15:14:02.842Z'
              - '2024-05-02T15:15:07.163Z'
            event_created_at: '2024-05-02T17:48:19.465Z'
    SuccessfulWebhookResponse2:
      summary: A successful webhook endpoint object.
      value:
        id: wep_456
        url: https://my_endpoint.xyz/hooks
        status: active
        public_key: '-----BEGIN PUBLIC KEY-----\nFAKEc27UdTQxxG4a5w0BAQEFAAOCAQ8AMIIBCgKCAQEAtYhc6PV2LOs/nqDRHi0B\nMKTsdMLHtg58a1NDxaYfw4IZJ3hpy1qIFUgt5X0HhCYZE0Y40MyLGIejPyitEjYw\ni9/aE+9F/PN+btqN7OK6cVuF9s/R9cxG4a5w0BAQEXrUO5T8GXNAMmRr0KFh8yPv\nfIgpoZn5ZhnyRbZpDvrxHzLmcZJFAX8Ca+KZLzgGVybEqJtP6fKAT0zrrUS1z44s\nRDOLiXl543cRAmBnUyrT6cXiNz/PNbm4zRK5Nx7LGxBFrCWQCao4Yi8hrwWsnHxg\n0Tcy3UyZhAcgL6ydVJfLD5x58Ri4BN32WPBtgSSO6JxZZwCiX0d1BOgq7+eNgmzN\nJQIDAQAB\n-----END PUBLIC KEY-----\n'
    SuccessfulWebhookUpdateResponse:
      summary: Successful webhook endpoint update
      value:
        id: wep_123
        url: https://my_updated_endpoint.xyz/hooks
        status: active
        public_key: '-----BEGIN PUBLIC KEY-----\nFJJ3hFnaPLmxxG4a5w0BAQEFAAOCAQ8AMIIBCgKCAQEAtYhc6PV2LOs/nqDRHi0B\nMKTsdMLHtg58a1NDxaYfw4IZJ3hpy1qIFUgt5X0HhCYZE0Y40MyLGIejPyitEjYw\ni9/aE+9F/PN+btqN7OK6cVuF9s/R9cZCtNc27UdTQXrUO5T8GXNAMmRr0KFh8yPv\nfIgpoZn5ZhnyRbZpDvrxHzLmcZJFAX8Ca+KZLzgGVybEqJtP6fKAT0zrrUS1z44s\nRDOLiXl543cRAmBnUyrT6cXiNz/PNbm4zRK5Nx7LGxBFrCWQCao4Yi8hrwWsnHxg\n0Tcy3UyZhAcgL6ydVJfLD5x58Ri4BN32WPBtgSSO6JxZZwCiX0d1BOgq7+eNgmzN\nJQIDAQAB\n-----END PUBLIC KEY-----\n'
        event_categories:
        - customer
        - liquidation_address
        - virtual_account
        - virtual_account.activity
        - card_account
        - card_transaction
        - card_withdrawal
        - posted_card_account_transaction
  schemas:
    WebhookEvent:
      required:
      - api_version
      - event_id
      - event_developer_id
      - event_category
      - event_type
      - event_object_id
      - event_object
      - event_object_changes
      - event_created_at
      properties:
        api_version:
          type: string
          readOnly: true
        event_id:
          $ref: '#/components/schemas/Id'
          readOnly: true
        event_developer_id:
          type: string
          readOnly: true
          description: The developer ID of the developer
        event_sequence:
          type: integer
          readOnly: true
        event_category:
          $ref: '#/components/schemas/WebhookEventCategory'
        event_type:
          type: string
          description: The values here will be prefixed with the event_category. For example, a customer created event will be `customer.created`
          enum:
          - created
          - updated
          - updated.status_transitioned
          - deleted
          - canceled
        event_object_id:
          $ref: '#/components/schemas/Id'
          readOnly: true
        event_object_status:
          type: string
          readOnly: true
          enum:
          - not_started
          - incomplete
          - active
          - rejected
          - under_review
          - manual_review
          - awaiting_ubo
          - approved
          - awaiting_funds
          - funds_received
          - payment_submitted
          - payment_processed
          - in_review
          - canceled
          - error
          - returned
          - refund_in_flight
          - refund_failed
          - refunded
          - undeliverable
        event_object:
          type: object
          description: The object that was affected by the event
          readOnly: true
        event_object_changes:
          type: object
          description: The changes that were made to the object
          readOnly: true
        event_created_at:
          type: string
          format: date-time
          readOnly: true
    WebhookEventCategory:
      type: string
      description: The category of the webhook event
      enum:
      - customer
      - kyc_link
      - liquidation_address.drain
      - static_memo.activity
      - transfer
      - virtual_account.activity
      - bridge_wallet.activity
      - card_account
      - card_transaction
      - card_withdrawal
      - posted_card_account_transaction
      - external_account
    Webhook:
      required:
      - id
      - url
      - status
      - public_key
      properties:
        id:
          type: string
          description: An identifier that uniquely identifies the webhook endpoint
          pattern: ^wep_[a-f0-9]+$
        url:
          type: string
          description: The URL that the webhook will send events to
        status:
          type: string
          description: The status of the webhook. Only active webhooks will receive events automatically.
          enum:
          - active
          - disabled
          - deleted
        public_key:
          type: string
          description: The public key (in PEM format) that should be used to verify the authenticity of webhook events
        event_categories:
          type: array
          description: The list of event categories that the webhook endpoint will receive
          minItems: 0
          items:
            $ref: '#/components/schemas/WebhookEventCategory'
    WebhookEventDeliveryLog:
      required:
      - status
      - event_id
      - response_body
      - created_at
      properties:
        status:
          type: integer
          description: The status code of the delivery
        event_id:
          $ref: '#/components/schemas/Id'
          description: The id of the event for the delivery
        response_body:
          type: string
          description: The response body of the delivery
        created_at:
          type: string
          format: date-time
          description: The time of the delivery
    Error:
      required:
      - code
      - message
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 256
        message:
          type: string
          minLength: 1
          maxLength: 512
        source:
          title: ErrorSource
          required:
          - location
          - key
          properties:
            location:
              type: string
              enum:
              - path
              - query
              - body
              - header
            key:
              type: string
              description: Comma separated names of the properties or parameters causing the error
    Id:
      description: A UUID that uniquely identifies a resource
      type: string
      pattern: '[a-z0-9]*'
      minLength: 1
      maxLength: 42
    PutWebhookPayload:
      properties:
        url:
          description: The new HTTPS URL that Bridge will send events to.
          type: string
          minLength: 1
        status:
          description: The new status of the webhook endpoint.  If set to "active", the webhook will be enabled and will send requests to the new URL.  If set to "disabled", the webhook will be disabled and will not send requests to the URL.
          type: string
          enum:
          - active
          - disabled
        event_categories:
          type: array
          description: The list of event categories that the webhook endpoint will receive. Note that if modified, the webhook endpoint will receive events for new categories only from the current point onwards.
          minItems: 0
          items:
            $ref: '#/components/schemas/WebhookEventCategory'
    SendWebhookPayload:
      properties:
        event_id:
          description: The ID of the event that will be delivered to your endpoint
          type: string
          minLength: 1
    CreateWebhook:
      required:
      - url
      - event_epoch
      properties:
        url:
          description: The URL that the webhook will send events to. It must use the HTTPS scheme and have a valid X.509 certificate. The URL doesn't need to be live, but the host must be reachable.
          type: string
          minLength: 1
        event_epoch:
          description: Specifies the starting point from which this webhook will receive events. This should usually be set to "webhook_creation", unless there is a reason why this webhook needs to process events from before its creation. When this value is set to "webhook_creation", the webhook will receive a small number of events preceding its creation for convenience.
          type: string
          enum:
          - webhook_creation
          - beginning_of_time
        event_categories:
          type: array
          description: The list of event categories that the webhook endpoint will receive
          minItems: 0
          items:
            $ref: '#/components/schemas/WebhookEventCategory'
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header