# Events And Webhooks

> Pull-based event audit history and push-based webhook delivery: how each works and when to use which.

Source: https://business-api-docs.youhodler.com/docs/concepts/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.

> **Practical rule:** Treat `Events` as the replay-safe audit source and `WebhookSubscription` as the delivery mechanism. Do not treat webhook delivery as the only source of truth.

## 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**
```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**
```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"
}
```