> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onconsul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and Webhooks

> Receive real-time notifications for object lifecycle events

To receive real-time notifications about events in the Consul API, register a webhook endpoint
from the **Developers, Webhooks** section of the
[dashboard](https://dashboard.onconsul.com). Consul sends HTTP POST requests to your URL when
subscribed events occur.

Event notifications include an `event_type` header and a JSON body that names the event and
points to the affected resource. Categories are intentionally simple: they only indicate whether
an object was `created` or `updated`. To get the full object state, fetch it from the relevant
API endpoint. This avoids issues with concurrent or out-of-order notifications.

<Note>
  Webhook delivery today is best-effort. Automatic retries, durable queueing, and request signing
  are on the roadmap but not yet shipped. Until they ship: design your handler to be idempotent,
  treat your webhook URL as a shared secret (serve it on a hard-to-guess path), and fall back to
  polling the relevant `GET` endpoint when you cannot afford to miss an event.
</Note>

### Webhook Delivery

Each subscribed event triggers a single `POST` to your endpoint with a JSON body. Your handler
should return a `2xx` quickly, ideally by enqueueing the event for an async worker.

Non-`2xx` responses, network errors, and timeouts (10 seconds) are logged and dropped; there is
no automatic retry yet. If your endpoint is temporarily unavailable, expect to lose events for
the duration of the outage.

### Headers

Each delivery includes the following headers:

| Header              | Description                                   |
| ------------------- | --------------------------------------------- |
| `Content-Type`      | Always `application/json`.                    |
| `User-Agent`        | Identifies the request as coming from Consul. |
| `Consul-Event-Type` | The event type, e.g. `payout.updated`.        |

Request signing is not currently emitted. When signing ships, deliveries will gain a
`Consul-Signature` header (HMAC-SHA256 over the raw body) and a `Consul-Timestamp` header for
replay protection; we'll publish a verification snippet alongside that release.

### Managing Subscriptions

Webhook subscriptions are managed exclusively from the dashboard. There is no API surface for
creating, listing, or deleting them, and OAuth-authenticated callers cannot manage subscriptions
on a user's behalf. To stop receiving events from an endpoint, delete the subscription from the
dashboard.

### Event Types

| Event                      | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `deposit.created`          | A fiat deposit has been initiated                      |
| `deposit.updated`          | A fiat deposit status changed (e.g. completed, failed) |
| `inbound_transfer.created` | A stablecoin deposit was received on-chain             |
| `payout.created`           | An on-chain payout transfer was initiated              |
| `payout.updated`           | A payout transfer status changed                       |
| `withdrawal.created`       | A fiat withdrawal (off-ramp) was initiated             |
| `withdrawal.updated`       | A fiat withdrawal status changed                       |
| `recipient.created`        | A new recipient was created                            |
| `recipient.updated`        | A recipient was updated                                |