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_type
  • aggregate
  • trace_id
  • subject_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 its scope_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

application/json
{
  "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

application/json
{
  "event_types": [
    "operations.withdrawal.settled.v1"
  ],
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "secret": "wh_secret_placeholder",
  "url": "https://example.com/webhooks"
}