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 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 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. Defaults to all events.

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 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 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 and will be retried.

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.