Skip to main content
DecimalAI sends outbound HTTP webhooks when notable events happen in your organization — for example, when a regression is detected on a newly-shipped manifest, or when your usage is approaching plan limits. Configure a single webhook URL per organization. DecimalAI POSTs a JSON body to that URL for every enabled event.
Webhooks support HMAC signing (X-Decimal-Signature) for verifiable delivery, and regression.detected deliveries are automatically retried with backoff on failure — every other event is delivered once (details). When a signing secret is configured for your org, deliveries are signed so you can verify them; to enable signing, email hello@decimal.ai — there is no self-serve secret setting yet. Delivery is still subject to a 5-second per-attempt timeout — acknowledge fast and process asynchronously.

Setup

Configure webhooks with the PATCH /api/v1/org/notifications API (admin role). There is no dashboard UI for this yet.
  • Webhook URL — the HTTPS endpoint that receives events (must be https://).
  • Enabled events — which event types to send. When events has never been set, every event is dispatched.
GET /api/v1/org/notifications reports a narrower default than dispatch uses — five events (manifest.changed, usage.warning, usage.limit_reached, payment.failed, payment.confirmed), omitting regression.detected, regression.resolved, subagent.drift and skill.safety_status_changed. PATCH persists whatever list it is handed, so a read-modify-write round trip (GET the settings, change webhook_url, PATCH the whole object back) silently turns those four off. Send only the keys you are changing.

Event types

Payload format

Every webhook body has the same envelope. The data field carries event-specific fields.
The data field for each event:

Headers

Every webhook request includes:

Verifying webhooks

When your org has a webhook secret configured, every webhook request carries an X-Decimal-Signature header of the form sha256=<hex_digest> — an HMAC-SHA256 over the raw request body bytes using your secret. Verify it before trusting the payload. To set or rotate the signing secret, email hello@decimal.ai.
The signature covers the exact bytes DecimalAI sent. Verify against await request.body() (or your framework’s raw-body accessor) — re-serializing the parsed JSON can reorder keys and break the comparison.

Receiving — example handlers

Signing is opt-in (email hello@decimal.ai), so until a secret is configured your endpoint is a public, unauthenticated POST that anyone can page your on-call team with. Configure a secret and verify every delivery, as both handlers below do — and treat an unsigned request as untrusted.

Retries and delivery

Each delivery attempt has a 5-second timeout. If your endpoint returns a non-2xx response or times out, the dispatch is recorded as failed. Retries apply to regression.detected only. A background scheduler replays failed regression-alert dispatches with backoff (and jitter), up to 3 attempts, before giving up. Every other event is delivered once — a failed attempt is recorded but never re-fired, so a receiver that is down or slow when the event fires will not see it again. Because retries can redeliver the same event, treat your handler as idempotent: deduplicate on the X-Decimal-Event-Id header so a replayed delivery is a no-op. If your webhook handler is slow or unreliable, return 200 immediately and process asynchronously. Anything longer than 5 seconds counts as a failed attempt.

Disabling webhooks

Set webhook_url to null via the PATCH /api/v1/org/notifications API. Notifications for events that have no configured channel are silently dropped (the events still happen and are visible in the dashboard).

Next Steps

Errors

HTTP status codes and how to handle them.

Roadmap

What’s shipped (HMAC signing, retry) and what’s still in flight.