Event structure

Bridge now supports webhook events for the following categories:

customer
kyc_link
liquidation_address.drain
static_memo.activity
transfer
virtual_account.activity
card_account
card_transaction
posted_card_account_transaction
card_withdrawal

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

Category	Supported Event Types
`customer`	`created`, `updated`, `updated.status_transitioned`, `deleted`
`kyc_link`	`created`, `updated`, `updated.status_transitioned`
`liquidation_address.drain`	`created`, `updated`, `updated.status_transitioned`
`static_memo.activity`	`created`, `updated`
`transfer`	`created`, `updated`, `updated.status_transitioned`
`virtual_account.activity`	`created`, `updated`
`card_account`	`created`, `updated`, `updated.status_transitioned`
`card_transaction`	`created`, `updated`, `updated.status_transitioned`
`posted_card_account_transaction`	`created`

Event Object Schema

Each webhook payload includes:

Field	Description
`api_version`	Current version of Bridge APIs (`v0`).
`event_id`	Globally unique event identifier. Useful as an idempotency key.
`event_category`	Category of the event (e.g., `virtual_account.activity`).
`event_type`	Formatted as `<event_category>.<mutation_type>`.
`event_object_id`	Same value as `event_object.id` (duplicated for easy access).
`event_object_status`	Optional. Populated when the object has a concept of status (e.g., `kyc_status`, `transfer_status`).
`event_object`	The full resource data, matching the structure in Bridge’s API reference.
`event_object_changes`	Diffs from the previous event (only present on updates).
`event_created_at`	Timestamp 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 Category	Schema Documentation
`transfer`	Transfer API Reference
`virtual_account.activity`	Virtual Account Activity
`customer`	Customer API Reference
`kyc_link`	KYC Link API Reference
`liquidation_address.drain`	Liquidation Address
`static_memo.activity`	Static Memo Activity

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

awaiting_funds
funds_received
payment_processed

{
"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"
}

{
  "api_version": "v0",
  "event_id": "wh_789xyz654mno",
  "event_developer_id": "dev_444ddd555eee666fff",
  "event_category": "transfer",
  "event_type": "updated.status_transitioned",
  "event_object_id": "tr_xyz789abc123",
  "event_object_status": "funds_received",
  "event_object": {
    "id": "tr_xyz789abc123",
    "state": "funds_received",
    "amount": "1.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_bob",
    "source": {
      "currency": "usdb",
      "payment_rail": "bridge_wallet",
      "bridge_wallet_id": "wallet_bob_usdb"
    },
    "destination": {
      "currency": "usdb",
      "payment_rail": "solana",
      "to_address": "9uYxZmV1KxJn7oVPW6bLUhF3cGQsk8vvMf1sQdPE6K4"
    },
    "receipt": {
      "gas_fee": "0.0",
      "exchange_fee": "0.0",
      "developer_fee": "0.0",
      "initial_amount": "1.00",
      "subtotal_amount": "1.00",
      "final_amount": "1.00",
      "destination_tx_hash": "4gJH6oXpZUNgC1QLh8mXNPF92LtLKzHZj5eHuQrdQAgB"
    },
    "created_at": "2025-06-11T21:27:00.000Z",
    "updated_at": "2025-06-11T21:27:01.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "funds_received"]
  },
  "event_created_at": "2025-06-11T21:27:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_t8TAhPPYrRV2v8Asi9ed3sw",
  "event_developer_id": "371983-uery-1238-1238971",
  "event_category": "transfer",
  "event_type": "updated.status_transitioned",
  "event_object_id": "fecffc8b-ed5e-48ae-bd24-b36268330b32",
  "event_object_status": "payment_processed",
  "event_object": {
    "id": "transfer_abc123",
    "state": "payment_processed",
    "amount": "50.0",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdb",
      "payment_rail": "bridge_wallet",
      "bridge_wallet_id": "wallet_alice_usdb"
    },
    "destination": {
      "currency": "usdb",
      "payment_rail": "solana",
      "to_address": "9uYxZmV1KxJn7oVPW6bLUhF3cGQsk8vvMf1sQdPE6K4"
    },
    "receipt": {
      "url": "https://dashboard.bridge.xyz/transaction/transfer_abc123/receipt/receipt_xyz456",
      "gas_fee": "0.0",
      "exchange_fee": "0.0",
      "developer_fee": "0.0",
      "initial_amount": "50.0",
      "subtotal_amount": "50.0",
      "final_amount": "50.0",
      "destination_tx_hash": "3gJH6oXpZUNgC1QLh8mXNPF92LtLKzHZj5eHuQrdQAgB"
    },
    "created_at": "2025-07-15T23:55:39.411Z",
    "updated_at": "2025-07-15T23:55:58.645Z"
  },
  "event_object_changes": {
    "state": [ "payment_submitted", "payment_processed" ]
  },
  "event_created_at": "2024-02-01T04:32:28.978Z"
}

Virtual Accounts

virtual_account.activity.created
virtual_account.activity.updated

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"
}

{
"api_version": "v0",
"event_id": "wh_t8trBtrPEqeFYLrQD9Zjog4",
"event_category": "virtual_account.activity",
"event_type": "virtual_account.activity.updated",
"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",
"destination_tx_hash": "0xa7de792daa970f89cdb36dbce93026d10942ea24",
"exchange_fee_amount": "10.0",
"developer_fee_amount": "20.0"
},
"event_object_changes": {
"destination_tx_hash": [ null, "0xa7de792daa970f89cdb36dbce93026d10942ea24" ]
},
"event_created_at": "2024-02-01T04:34:13.763Z"
}

KYC Links

kyc_link.updated.status_transitioned

{
    "api_version": "v0",
    "event_id": "wh_tmyqyd9q5nsVJazfux9EiQC",
    "event_category": "kyc_link",
    "event_type": "kyc_link.updated.status_transitioned",
    "event_object_id": "3694522e-6bed-4660-a803-f599b50c7691",
    "event_object_status": "incomplete",
    "event_object": {
        "id": "3694522e-6bed-4660-a803-f599b50c7691",
        "type": "individual",
        "email": "[email protected]",
        "kyc_link": "<KYC link>",
        "tos_link": "<ToS link>",
        "full_name": "Danyka Wintheiser",
        "created_at": "2024-02-09T16:48:11.531Z",
        "kyc_status": "incomplete",
        "tos_status": "approved",
        "customer_id": null,
        "persona_inquiry_type": "gov_id_db"
    },
    "event_object_changes": {
        "kyc_status": [
            "not_started",
            "incomplete"
        ],
        "tos_status": [
            "pending",
            "approved"
        ]
    },
    "event_created_at": "2024-02-09T17:00:43.709Z"
}

Orchestration

Wallets

Issuance

Cards

Customers

Additional information

Event structure

Supported Event Types

Event Object Schema

Event Object Schema Reference

Supported Mutation Types

Examples

Transfers

Virtual Accounts

KYC Links

Orchestration

Wallets

Issuance

Cards

Customers

Additional information

​Supported Event Types

​Event Object Schema

​Event Object Schema Reference

​Supported Mutation Types

​Examples

​Transfers

​Virtual Accounts

​KYC Links

Supported Event Types

Event Object Schema

Event Object Schema Reference

Supported Mutation Types

Examples

Transfers

Virtual Accounts

KYC Links