YOUHODLERBusiness API
Get access
View as Markdown

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
  • subscriptions are enterprise-scoped

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
{
  "id": "evt_123",
  "event_type": "operation.withdrawal.executed.v1",
  "aggregate": {
    "kind": "withdrawal",
    "ref": "withdrawals/op_123"
  },
  "trace_id": "trace_789",
  "data": {
    "status": "executed"
  }
}

Request Body

application/json
{
  "enterprise_id": "11111111-1111-4111-8111-111111111111",
  "url": "https://example.com/hooks/b2b2x",
  "event_types": [
    "tenant.client.created.v1",
    "operation.withdrawal.executed.v1"
  ],
  "secret": "replace-me"
}