Skip to main content
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.

​
Headers

Each delivery includes the following headers: 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