Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Bridge now supports webhook events for the following categories:
  • customer
  • kyc_link
  • liquidation_address.drain
  • static_memo.activity
  • transfer
  • virtual_account.activity
  • bridge_wallet.activity
  • card_account
  • card_transaction
  • posted_card_account_transaction
  • card_withdrawal
  • external_acccount
Additional event categories will be added soon.

💬 Feedback welcome — Let us know which event types you’d like to see prioritized next.

​
Supported Event Types

CategorySupported Event Types
customercreated, updated, updated.status_transitioned, deleted
kyc_linkcreated, updated, updated.status_transitioned
liquidation_address.draincreated, updated, updated.status_transitioned
static_memo.activitycreated, updated
transfercreated, updated, updated.status_transitioned
virtual_account.activitycreated, updated
bridge_wallet.activitycreated, updated
card_accountcreated, updated, updated.status_transitioned
card_transactioncreated, updated, updated.status_transitioned
posted_card_account_transactioncreated
external_acccountcreated, updated

​
Event Object Schema

Each webhook payload includes:
FieldDescription
api_versionCurrent version of Bridge APIs (v0).
event_idGlobally unique event identifier. Useful as an idempotency key.
event_categoryCategory of the event (e.g., virtual_account.activity).
event_typeFormatted as <event_category>.<mutation_type>.
event_object_idSame value as event_object.id (duplicated for easy access).
event_object_statusOptional. Populated when the object has a concept of status (e.g., kyc_status, transfer_status).
event_objectThe full resource data, matching the structure in Bridge’s API reference.
event_object_changesDiffs from the previous event (only present on updates).
event_created_atTimestamp of the event in ISO 8601 format.

​
Event Object Schema Reference

The event_object field contains the full resource data, matching the structure returned by corresponding API endpoints. Webhooks and API responses use identical rendering logic, ensuring schema consistency.
Event CategorySchema Documentation
transferTransfer API Reference
virtual_account.activityVirtual Account Activity
customerCustomer API Reference
kyc_linkKYC Link API Reference
liquidation_address.drainLiquidation Address
static_memo.activityStatic Memo Activity
bridge_wallet.activityBridge Wallet transaction history API
external_acccountExternal Account API Reference

​
Supported Mutation Types

Each event can have the following mutation types:
  • created
  • updated
  • updated.status_transitioned (for state transitions like KYC or Transfer status)
  • deleted (if applicable)

​
Examples

For cards-related webhook events, see the scenarios outlined in this cards-specific webhook scenarios page.

​
Transfers

{
"api_version": "v0",
"event_id": "wh_123abc456def",
"event_developer_id": "dev_111aaa222bbb333ccc",
"event_category": "transfer",
"event_type": "created",
"event_object_id": "tr_abc123xyz789",
"event_object_status": "awaiting_funds",
"event_object": {
"id": "tr_abc123xyz789",
"state": "awaiting_funds",
"amount": "1500.00",
"currency": "usd",
"developer_fee": "0.0",
"client_reference_id": null,
"on_behalf_of": "cust_alice",
"source": {
  "currency": "usdc",
  "from_address": "0x1111111111111111111111111111111111111111",
  "payment_rail": "polygon"
},
"destination": {
  "currency": "usd",
  "payment_rail": "ach",
  "external_account_id": "external-account-123"
},
"receipt": {
  "gas_fee": "0.0",
  "exchange_fee": "0.0",
  "developer_fee": "0.0",
  "initial_amount": "1500.00",
  "subtotal_amount": "1500.00",
  "final_amount": "1500.00"
},
"created_at": "2025-07-22T11:26:55.000Z",
"updated_at": "2025-07-22T11:26:56.000Z"
},
"event_object_changes": {},
"event_created_at": "2025-07-22T11:26:00.000Z"
}

​
Bridge Wallet Activity

To receive Bridge Wallet activity events, create or update a webhook endpoint subscribed to bridge_wallet.activity.
Bridge Wallet activity webhooks deliver the same object returned by the Bridge Wallet transaction history API. 
{
  "api_version": "v0",
  "event_id": "wh_wallet_123",
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "bridge_wallet.activity",
  "event_type": "bridge_wallet.activity.created",
  "event_object_id": "bwe_123",
  "event_object_status": null,
  "event_object": {
    "id": "bwe_123",
    "bridge_wallet_id": "bw_123",
    "amount": "50.000000",
    "available_balance": "1050.000000",
    "currency": "usdc",
    "type": "deposit",
    "source": {
      "currency": "usd",
      "payment_rail": "ach"
    },
    "destination": {
      "currency": "usdc",
      "payment_rail": "ethereum",
      "tx_hash": "0xdeadbeef"
    },
    "payment_route": {
      "type": "drain",
      "customer_id": "cust_123",
      "drain_id": "drain_123",
      "liquidation_address_id": "la_123",
      "liquidation_address_address": "0x1111111111111111111111111111111111111111"
    },
    "created_at": "2025-01-01T00:00:00.000Z"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-01T00:00:00.000Z"
}

​
Virtual Accounts

Below is a creation event for a Virtual Account Activity event object
{
  "api_version": "v0",
  "event_id": "wh_t8TAhPPYrRV2v8Asi9ed3sw",
  "event_developer_id": "371983-uery-1238-1238971",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fecffc8b-ed5e-48ae-bd24-b36268330b32",
  "event_object_status": null,
  "event_object": {
    "id": "fecffc8b-ed5e-48ae-bd24-b36268330b32",
    "type": "payment_submitted",
    "amount": "1970.0",
    "source": {
      "description": "EXAMPLE TRANSACTION Brown-Beer Arnoldo Schimmel MD 01202024",
      "sender_name": "Brown-Beer",
      "payment_rail": "ach_push",
      "sender_bank_routing_number": "023883013"
    },
    "gas_fee": "0.0",
    "currency": "usdc",
    "created_at": "2024-02-01T04:31:43.342Z",
    "deposit_id": "c7fab38f-7b65-42d3-bc8d-a694cd1901c1",
    "customer_id": "6ed47d9c-03be-420c-8699-369707ca02e9",
    "subtotal_amount": "1970.0",
    "virtual_account_id": "22033ca5-a991-476c-ade9-911d10f0ece6",
    "exchange_fee_amount": "10.0",
    "developer_fee_amount": "20.0"
  },
  "event_object_changes": {
  },
  "event_created_at": "2024-02-01T04:32:28.978Z"
}

​
Customers

Initial creation via a KYC link before the customer has taken any action.
{
  "api_version": "v0",
  "event_id": "wh_2tEL5NVw3dkEpLRJz4dS8gqWYX1",
  "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab",
  "event_sequence": 1,
  "event_category": "customer",
  "event_type": "customer.created",
  "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A",
  "event_object_status": "not_started",
  "event_object": {
    "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "type": "individual",
    "status": "not_started",
    "persona_inquiry_type": "gov_id_db",
    "has_accepted_terms_of_service": false,
    "client_reference_id": null,
    "tos_link": "https://dashboard.bridge.xyz/tos/c_2tEKzQmNvR9xJfPdL8mY4hsBk3A",
    "rejection_reasons": [],
    "endorsements": [
      {
        "name": "base",
        "status": "incomplete",
        "requirements": {
          "complete": [],
          "pending": [],
          "missing": {
            "id_verification": "Identity verification required"
          },
          "issues": []
        }
      }
    ],
    "future_requirements_due": [],
    "created_at": "2025-11-19T21:14:58.328Z",
    "updated_at": "2025-11-19T21:14:58.328Z"
  },
  "event_object_changes": {},
  "event_created_at": "2025-11-19T21:14:58.328Z"
}