Events And Webhooks
Event delivery is split into two public surfaces.
These surfaces are related but not interchangeable. One is a pull-based audit stream. The other is a push-based delivery configuration that lets external systems react to state changes as they happen.
Mental Model
The event model exists so integrations can support both:
- active delivery to downstream systems
- delayed reconciliation, replay, and traceability
The two public surfaces divide that responsibility cleanly.
Events
BackboneEvent gives tenants a canonical audit and lifecycle stream with:
event_typeaggregatetrace_idsubject_attribution- event
data
Use the events API when you need filtered history, traceability, or delayed reconciliation.
Webhook Endpoints
WebhookSubscription lets a tenant register outbound delivery targets.
Important behaviors:
- updates use
If-Match - status transitions are explicit
- each subscription is scoped to an enterprise (
enterprises/<id>) or to a client (clients/<id>) through itsscope_ref
Use webhook endpoints when you want operational events pushed to your own systems.
Delivery And Replay
Use webhook delivery for real-time reaction, but keep event retrieval available for:
- retry and backfill
- downstream outage recovery
- audit reconstruction
- traceable lifecycle review
That split keeps delivery concerns separate from canonical history.
How This Appears In The API
Response
{
"aggregate": {
"type": "withdrawal",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"data": {
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"failure_reason": null,
"family": "withdrawal",
"fee_summary": {
"components": [
{
"amount": {
"currency": "USDC",
"value": "1.00"
},
"kind": "network_fee"
}
],
"total": {
"currency": "USDC",
"value": "1.00"
}
},
"fill_rate": null,
"occurred_at": "2026-05-01T10:00:00Z",
"operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"principal_amount": {
"currency": "USDC",
"value": "250.00"
},
"scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"status": "settled"
},
"event_type": "operations.withdrawal.settled.v1",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"metadata": null,
"occurred_at": "2026-05-01T10:00:00Z",
"partition_key": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"published_at": "2026-05-01T10:00:00Z",
"resource": "event",
"schema_version": 1,
"scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"subject_attribution": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"enterprise_binding": {
"tenant_type": "enterprise",
"topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"federation": null,
"identity_source": "platform-managed",
"initiated_by": null,
"subject": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"trace_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}Request Body
{
"event_types": [
"operations.withdrawal.settled.v1"
],
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"secret": "wh_secret_placeholder",
"url": "https://example.com/webhooks"
}