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 thePATCH /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
eventshas never been set, every event is dispatched.
Event types
Payload format
Every webhook body has the same envelope. Thedata field carries event-specific fields.
data field for each event:
manifest.changed
manifest.changed
regression.detected / regression.resolved
regression.detected / regression.resolved
usage.warning / usage.limit_reached
usage.warning / usage.limit_reached
payment.failed / payment.confirmed
payment.failed / payment.confirmed
subagent.drift
subagent.drift
skill.safety_status_changed
skill.safety_status_changed
Headers
Every webhook request includes:Verifying webhooks
When your org has a webhook secret configured, every webhook request carries anX-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
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 toregression.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
Setwebhook_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.