> ## 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. # Event structure 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 | **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` | | `bridge_wallet.activity` | `created`, `updated` | | `card_account` | `created`, `updated`, `updated.status_transitioned` | | `card_transaction` | `created`, `updated`, `updated.status_transitioned` | | `posted_card_account_transaction` | `created` | | `external_acccount` | `created`, `updated` | ## 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_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](/platform/orchestration/transfers/transfer) | | `virtual_account.activity` | [Virtual Account Activity](/platform/orchestration/virtual_accounts/virtual-account-events) | | `customer` | [Customer API Reference](/platform/customers/customers/api) | | `kyc_link` | [KYC Link API Reference](/platform/customers/customers/kyclinks) | | `liquidation_address.drain` | [Liquidation Address](/platform/orchestration/liquidation_address/liquidation_address) | | `static_memo.activity` | [Static Memo Activity](/platform/orchestration/more/staticmemos) | | `bridge_wallet.activity` | [Bridge Wallet transaction history API](/api-reference/bridge-wallets/get-transaction-history-for-a-bridge-wallet) | | `external_acccount` | [External Account API Reference](/api-reference/external-accounts/retrieve-an-external-account-object) | ## 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](https://apidocs.bridge.xyz/platform/cards/overview/webhooks) cards-specific webhook scenarios page. ### Transfers ```json theme={null} { "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" } ``` ```json theme={null} { "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" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_789ghi012jkl", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "in_review", "event_object": { "id": "tr_abc123xyz789", "state": "in_review", "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:28:10.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "in_review"] }, "event_created_at": "2025-07-22T11:28:10.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_t96YqUFLXfXxqJewhzz92qn", "event_developer_id": "f1959d8d-798e-418d-bd69-8d556ade827b", "event_sequence": 801, "event_category": "transfer", "event_type": "transfer.updated", "event_object_id": "37f16b41-85d2-4db3-96be-f305cb246b15", "event_object_status": "payment_submitted", "event_object": { "id": "37f16b41-85d2-4db3-96be-f305cb246b15", "state": "payment_submitted", "amount": "0.01", "source": { "currency": "usdc", "from_address": "41myj7T7vHPQ17SQFJdbJ35JrrYAgHzH1raFd9S8PvsM", "payment_rail": "bridge_wallet", "bridge_wallet_id": "9a5ac57a-ce6c-4419-86f5-8cf3adc91292" }, "receipt": { "gas_fee": "0.0", "exchange_fee": "0.0", "final_amount": "0.01", "developer_fee": "0.0", "initial_amount": "0.01", "subtotal_amount": "0.01", "destination_tx_hash": "3DrJCtEmQNaXA1VKLfihJn3MAHsfEwb2UALf6V3LvjutXadweMCmWUDoQzNiXT1d2UZBVbHwsmxLDaMUf3UgPpYX" }, "currency": "usd", "created_at": "2026-05-26T14:50:33.310Z", "updated_at": "2026-05-26T14:50:42.868Z", "destination": { "currency": "usdc", "to_address": "92ZfgbCPwvBTBSJUJoQJTQ7kr4M1wayi8d2FzHVfiXcV", "payment_rail": "solana" }, "on_behalf_of": "8570375f-125c-4913-9da5-3a33c029a060", "developer_fee": "0.0", "client_reference_id": "963d82b7-4773-446d-a9dc-741a4309b7ba" }, "event_object_changes": { "receipt": [ { "gas_fee": "0.0", "exchange_fee": "0.0", "final_amount": "0.01", "developer_fee": "0.0", "initial_amount": "0.01", "subtotal_amount": "0.01" }, { "gas_fee": "0.0", "exchange_fee": "0.0", "final_amount": "0.01", "developer_fee": "0.0", "initial_amount": "0.01", "subtotal_amount": "0.01", "destination_tx_hash": "3DrJCtEmQNaXA1VKLfihJn3MAHsfEwb2UALf6V3LvjutXadweMCmWUDoQzNiXT1d2UZBVbHwsmxLDaMUf3UgPpYX" } ], "updated_at": [ "2026-05-26T14:50:36.344Z", "2026-05-26T14:50:42.868Z" ] }, "event_created_at": "2026-05-26T14:50:43.149Z" } ``` ```json theme={null} { "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" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_345cde678fgh", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "kyc_required", "event_object": { "id": "tr_abc123xyz789", "state": "kyc_required", "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" }, "kyc_link": "https://bridge.withpersona.com/verify?inquiry-template-id=itmpl_abc&fields[em ail]=alice@example.com", "created_at": "2025-07-22T11:26:55.000Z", "updated_at": "2025-07-22T11:27:05.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "kyc_required"] }, "event_created_at": "2025-07-22T11:27:05.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_456def789ghi", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "kyc_in_review", "event_object": { "id": "tr_abc123xyz789", "state": "kyc_in_review", "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:35:00.000Z" }, "event_object_changes": { "state": ["kyc_required", "kyc_in_review"] }, "event_created_at": "2025-07-22T11:35:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_567efg890hij", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "developer_kyb_required", "event_object": { "id": "tr_abc123xyz789", "state": "developer_kyb_required", "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:27:02.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "developer_kyb_required"] }, "event_created_at": "2025-07-22T11:27:02.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_678fgh901ijk", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "underfunded", "event_object": { "id": "tr_abc123xyz789", "state": "underfunded", "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": "1200.00", "subtotal_amount": "1200.00", "final_amount": "1200.00" }, "created_at": "2025-07-22T11:26:55.000Z", "updated_at": "2025-07-22T11:27:10.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "underfunded"] }, "event_created_at": "2025-07-22T11:27:10.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_789ghi012jkl", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "undeliverable", "event_object": { "id": "tr_abc123xyz789", "state": "undeliverable", "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:45:00.000Z" }, "event_object_changes": { "state": ["payment_submitted", "undeliverable"] }, "event_created_at": "2025-07-22T11:45:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_890hij123klm", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "error", "event_object": { "id": "tr_abc123xyz789", "state": "error", "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:50:00.000Z" }, "event_object_changes": { "state": ["in_review", "error"] }, "event_created_at": "2025-07-22T11:50:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_901ijk234lmn", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "canceled", "event_object": { "id": "tr_abc123xyz789", "state": "canceled", "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:40:00.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "canceled"] }, "event_created_at": "2025-07-22T11:40:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_012jkl345mno", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "deactivated", "event_object": { "id": "tr_abc123xyz789", "state": "deactivated", "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-22T12:00:00.000Z" }, "event_object_changes": { "state": ["awaiting_funds", "deactivated"] }, "event_created_at": "2025-07-22T12:00:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_123klm456nop", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "missing_return_policy", "event_object": { "id": "tr_abc123xyz789", "state": "missing_return_policy", "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:32:00.000Z" }, "event_object_changes": { "state": ["payment_processed", "missing_return_policy"] }, "event_created_at": "2025-07-22T11:32:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_234lmn567opq", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "returned", "event_object": { "id": "tr_abc123xyz789", "state": "returned", "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-23T09:00:00.000Z" }, "event_object_changes": { "state": ["payment_processed", "returned"] }, "event_created_at": "2025-07-23T09:00:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_345mno678pqr", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "refund_in_flight", "event_object": { "id": "tr_abc123xyz789", "state": "refund_in_flight", "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-23T09:05:00.000Z" }, "event_object_changes": { "state": ["returned", "refund_in_flight"] }, "event_created_at": "2025-07-23T09:05:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_456nop789qrs", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "refunded", "event_object": { "id": "tr_abc123xyz789", "state": "refunded", "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-23T09:20:00.000Z" }, "event_object_changes": { "state": ["refund_in_flight", "refunded"] }, "event_created_at": "2025-07-23T09:20:00.000Z" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_567opq890rst", "event_developer_id": "dev_111aaa222bbb333ccc", "event_category": "transfer", "event_type": "updated.status_transitioned", "event_object_id": "tr_abc123xyz789", "event_object_status": "refund_failed", "event_object": { "id": "tr_abc123xyz789", "state": "refund_failed", "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-23T09:20:00.000Z" }, "event_object_changes": { "state": ["refund_in_flight", "refund_failed"] }, "event_created_at": "2025-07-23T09:20: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-reference/bridge-wallets/get-transaction-history-for-a-bridge-wallet). ```json theme={null} { "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" } ``` ```json theme={null} { "api_version": "v0", "event_id": "wh_wallet_456", "event_developer_id": "f1959d8d-798e-418d-bd69-8d556ade827b", "event_sequence": 621, "event_category": "bridge_wallet.activity", "event_type": "bridge_wallet.activity.updated", "event_object_id": "808c20d4-3b83-440c-88d4-140fd2ba4015", "event_object_status": null, "event_object": { "id": "808c20d4-3b83-440c-88d4-140fd2ba4015", "type": "undeliverable", "amount": "0.01", "currency": "usdc", "source": { "payment_rail": "solana", "currency": "usdc" }, "destination": { "payment_rail": "bridge_wallet", "currency": "usdc" }, "payment_route": { "type": "transfer", "customer_id": "8570375f-125c-4913-9da5-3a33c029a060", "transfer_id": "232d9152-e2dc-4057-9775-ea3a9e32b5f7" }, "bridge_wallet_id": "9a5ac57a-ce6c-4419-86f5-8cf3adc91292", "available_balance": "4.46", "created_at": "2026-04-29T17:26:49.601Z" }, "event_object_changes": {}, "event_created_at": "2026-04-29T17:27:04.308Z" } ``` ### Virtual Accounts Below is a creation event for a Virtual Account Activity event object ```json theme={null} { "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" } ``` ```json theme={null} { "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" } ``` ### Customers Initial creation via a KYC link before the customer has taken any action. ```json theme={null} { "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" } ``` Customer has started KYC but hasn't finished. ```json theme={null} { "api_version": "v0", "event_id": "wh_3fGH7NPq5eLmRTKwV2xB9jrZYc4", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 2, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "incomplete", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "incomplete", "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": ["government_id"], "pending": ["selfie_verification"], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T21:22:14.105Z" }, "event_object_changes": { "status": ["not_started", "incomplete"] }, "event_created_at": "2025-11-19T21:22:14.105Z" } ``` Customer must complete an additional questionnaire before proceeding. ```json theme={null} { "api_version": "v0", "event_id": "wh_8rST1UVw4XYz5ABc6DEf7GHijkl", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 3, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "awaiting_questionnaire", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "awaiting_questionnaire", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "incomplete", "requirements": { "complete": ["government_id", "selfie_verification"], "pending": ["questionnaire"], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T21:48:09.761Z" }, "event_object_changes": { "status": ["incomplete", "awaiting_questionnaire"] }, "event_created_at": "2025-11-19T21:48:09.761Z" } ``` Business customer has completed KYB but verification of ultimate beneficial owners (UBOs) is still pending. ```json theme={null} { "api_version": "v0", "event_id": "wh_6pQR9STu2VWx3YZa4BCd5EFg6HIj", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 3, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_7bXNpRmLqD4kJfWvA2sY9hcTz8E", "event_object_status": "awaiting_ubo", "event_object": { "id": "c_7bXNpRmLqD4kJfWvA2sY9hcTz8E", "first_name": "Acme Corp", "last_name": null, "email": "kyb@example.com", "type": "business", "status": "awaiting_ubo", "persona_inquiry_type": "business", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "incomplete", "requirements": { "complete": ["business_verification"], "pending": ["ubo_verification"], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T21:55:30.214Z" }, "event_object_changes": { "status": ["incomplete", "awaiting_ubo"] }, "event_created_at": "2025-11-19T21:55:30.214Z" } ``` Customer completed KYC submission; awaiting manual review. ```json theme={null} { "api_version": "v0", "event_id": "wh_5kPQ2XRw8nBdSfLmC7vJ4tzNhe9", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 3, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "under_review", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "under_review", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "incomplete", "requirements": { "complete": ["government_id", "selfie_verification"], "pending": [], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T21:35:42.917Z" }, "event_object_changes": { "status": ["incomplete", "under_review"], "has_accepted_terms_of_service": [false, true] }, "event_created_at": "2025-11-19T21:35:42.917Z" } ``` Customer passed KYC and is fully active. ```json theme={null} { "api_version": "v0", "event_id": "wh_9mRS4VTx1oCeWgNqA6uK8yzBpf2", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 4, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "approved", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "approved", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "approved", "requirements": { "complete": ["government_id", "selfie_verification"], "pending": [], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T22:01:08.443Z" }, "event_object_changes": { "status": ["under_review", "approved"] }, "event_created_at": "2025-11-19T22:01:08.443Z" } ``` Customer failed KYC. Includes rejection reasons. ```json theme={null} { "api_version": "v0", "event_id": "wh_7nWD6YUz3qAfXhMrE5tP1bcLjk8", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 4, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "rejected", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "rejected", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [ { "reason": "id_verification_failed", "message": "We were unable to verify your identity. Please ensure your government-issued ID is valid and the photo is clear." } ], "endorsements": [ { "name": "base", "status": "revoked", "requirements": { "complete": [], "pending": [], "missing": {}, "issues": [ "id_verification_failed" ] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-19T22:05:31.762Z" }, "event_object_changes": { "status": ["under_review", "rejected"] }, "event_created_at": "2025-11-19T22:05:31.762Z" } ``` Customer account has been paused, typically due to an active compliance flag. ```json theme={null} { "api_version": "v0", "event_id": "wh_2mNO5PQr8STu9VWx1YZa3BCde4F", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 5, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "paused", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "paused", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "approved", "requirements": { "complete": ["government_id", "selfie_verification"], "pending": [], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-20T10:12:44.882Z" }, "event_object_changes": { "status": ["approved", "paused"] }, "event_created_at": "2025-11-20T10:12:44.882Z" } ``` Customer account has been permanently closed. ```json theme={null} { "api_version": "v0", "event_id": "wh_9vWX3YZa6BCd7EFg8HIj1JKlmno", "event_developer_id": "b2f58e14-3c8d-4a1e-9b7a-1234567890ab", "event_sequence": 6, "event_category": "customer", "event_type": "customer.updated.status_transitioned", "event_object_id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "event_object_status": "offboarded", "event_object": { "id": "c_2tEKzQmNvR9xJfPdL8mY4hsBk3A", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "type": "individual", "status": "offboarded", "persona_inquiry_type": "gov_id_db", "has_accepted_terms_of_service": true, "client_reference_id": null, "tos_link": null, "rejection_reasons": [], "endorsements": [ { "name": "base", "status": "revoked", "requirements": { "complete": [], "pending": [], "missing": {}, "issues": [] } } ], "future_requirements_due": [], "created_at": "2025-11-19T21:14:58.328Z", "updated_at": "2025-11-20T11:03:22.119Z" }, "event_object_changes": { "status": ["paused", "offboarded"] }, "event_created_at": "2025-11-20T11:03:22.119Z" } ``` ### KYC Links ```json theme={null} { "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": "danyka+wintheiser@quigley.xyz", "kyc_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" } ```