Webhooks support HMAC signing (
X-Decimal-Signature) for verifiable delivery and automatic retry with backoff on failure. When a signing secret is configured for your org, deliveries are signed so you can verify them; to enable signing, email support@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. Defaults to all events.
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
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 support@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 and automatically retried — a background scheduler replays failed dispatches with backoff (and jitter), up to a few attempts, before giving up. Because retries can redeliver the same event, treat your handler as idempotent: deduplicate on theX-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 and will be retried.
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.