Guides

Event Structure

Suggest Edits

Bridge currently supports webhook events for the following API objects:

  • customer
  • kyc_link
  • liquidation_address.drain
  • static_memo.activity
  • transfer
  • virtual_account.activity

More event types will be added over time — your feedback is welcome. Let us know which event categories you'd like to see prioritized.

Example Events

virtual_account.activity.created

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

virtual_account.activity.updated

For update events, the field event_object_changes will be populated with diffs from the previous webhook event in the event_object:

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

Event Definition

Metadata

FieldDescription
api_versionAPI version, currently always "v0"
event_idUnique, immutable ID for this event. Useful for idempotency and deduplication.
event_created_atISO 8601 timestamp of when the event was generated.
event_developer_idID associated with the developer account receiving the event.

💡

Once an event_id gets assigned to an event, it remains unchanged. It’s a good candidate to use as an idempotency key by the application logic on the receiving end.

Event Routing

FieldDescription
event_categoryCategory of the event, e.g. transfer, kyc_link, customer, virtual_account.activity, etc.
event_typeFully qualified event type in the format <event_category>.<mutation_type>.

Supported mutation types:

  • created
  • updated
  • updated.status_transitioned (if status changed)
  • deleted (where applicable)

Object Details

FieldDescription
event_object_idShortcut reference to the object's id (also found in event_object.id)
event_object_statusHigh-level status of the object, when applicable (e.g., incomplete, approved)
event_objectThe full resource object payload, structured identically to its API representation.
event_object_changesFor updated events: a dictionary showing the diff between previous and current values. The format is { "field_name": ["old_value", "new_value"] }

Supported Event Types

Event CategorySupported Event Types
customercustomer.created,customer.updated,customer.updated.status_transitioned,customer.deleted
kyc_linkkyc_link.created,kyc_link.updated,kyc_link.updated.status_transitioned
liquidation_address.drainliquidation_address.drain.created,liquidation_address.drain.updated,liquidation_address.drain.updated.status_transitioned
static_memo.activitystatic_memo.activity.created,static_memo.activity.updated
transfertransfer.created,transfer.updated,transfer.updated.status_transitioned
virtual_account.activityvirtual_account.activity.created,virtual_account.activity.updated

Updated 19 days ago