To receive real-time notifications about events in the Consul API, register a webhook endpoint
from the Developers, Webhooks section of the
dashboard. 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.
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.
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.
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. |
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 |
