customerkyc_linkliquidation_address.drainstatic_memo.activitytransfervirtual_account.activitybridge_wallet.activitycard_accountcard_transactionposted_card_account_transactioncard_withdrawalexternal_acccount
💬 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_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
Theevent_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 |
bridge_wallet.activity | Bridge Wallet transaction history API |
external_acccount | External Account API Reference |
Supported Mutation Types
Each event can have the following mutation types:createdupdatedupdated.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
- in_review
- payment_submitted
- payment_processed
- kyc_required
- kyc_in_review
- developer_kyb_required
- underfunded
- undeliverable
- error
- canceled
- deactivated
- missing_return_policy
- returned
- refund_in_flight
- refunded
- refund_failed
{
"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_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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"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.created
- bridge_wallet.activity.updated
{
"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"
}
{
"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
- virtual_account.activity.created
- payment_sumbitted
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"
}
Customers
- not_started
- incomplete
- awaiting_questionnaire
- awaiting_ubo
- under_review
- approved
- rejected
- paused
- offboarded
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"
}
Customer has started KYC but hasn’t finished.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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
- 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": "danyka+wintheiser@quigley.xyz",
"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"
}