Skip to main content
Orbitrage notifies you when a metric crosses a threshold you set, or when its detectors spot an anomaly on their own. Both deliver to a webhook URL or to Slack.

​
Threshold alerts

Create an alert from the Customise page or by asking Ask Analytics (create_alert). An alert watches one metric over a sliding window and fires when it crosses your threshold.
​
metric
string
required
One of calls_count, cost_total, savings_total, tokens_in, tokens_out, tokens_total, errors_count, tool_calls_count, unique_users, unique_models, avg_latency_ms, p95_latency_ms.
​
threshold_op
string
required
Comparison: >, <, >=, or <=.
​
threshold_value
number
required
The value to compare against.
​
window_minutes
number
default:"5"
Sliding window to evaluate the metric over (1–1440).
​
cooldown_minutes
number
default:"60"
Minimum gap between fires (1–10080).
​
webhook_url
string
required
An https:// receiver. A hooks.slack.com URL is auto-formatted for Slack.
​
filter
object
Optional scoping by workflow_id, end_user_id, model, provider, or tool_name.

​
Webhook payload

When a non-Slack alert fires, Orbitrage POSTs JSON and signs it: 
{
  "event": "alert.fired",
  "alert_id": "uuid",
  "alert_name": "cost spike on Prod",
  "org_id": "uuid",
  "metric": "cost_total",
  "threshold": { "op": ">", "value": 50, "window_minutes": 60 },
  "current_value": 61.2,
  "filter": { "workflow_id": "..." },
  "fired_at": "2026-06-07T14:00:00Z"
}
The request carries X-Orbitrage-Signature: <hex>, an HMAC-SHA256 of the raw body using the alert’s webhook secret (shown once at creation). Verify it: 
import hmac, hashlib
def verify(body_bytes, header_hex, secret):
    digest = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(digest, header_hex)
Slack webhooks (hooks.slack.com) receive Block Kit instead of the signed JSON — the URL itself is the secret, so no signature is added.

​
Anomaly detection (automatic)

Beyond explicit thresholds, Orbitrage learns each org’s normal pattern and alerts on deviations — no configuration beyond a Slack connection.
  • Baselines are computed per hour-of-week (so 3pm Tuesday is judged against past 3pm Tuesdays), as a rolling mean and standard deviation over calls, cost, errors, and tokens.
  • Each hour, the just-completed hour is compared to its baseline. If it deviates beyond a Z-threshold (default 3) — and the same metric hasn’t already fired this hour — a Block Kit message is posted to your Slack channel.
  • Anomalies are skipped when there aren’t enough samples yet (minimum 3 for that hour-of-week) or while a cooldown is active.
Same statistical engine as the Intelligence layer.

​
Delivering to Slack

PathHow
Connected Slack appInstall from Customise → Slack. Powers proactive anomaly alerts and the Slack agent.
Per-org webhookPaste an incoming-webhook URL at Customise → Slack integration. Used by anomaly alerts and the send_to_slack tool.
Per-alert webhookSet any alert’s webhook_url to a hooks.slack.com URL.

​
Scheduling (self-hosted note)

Alerts and anomaly checks run on a schedule (every minute for threshold alerts; hourly for anomalies) authenticated with a shared CRON_SECRET. The managed platform wires this up already; if you self-host, schedule the cron endpoints via pg_cron + pg_net or any external scheduler.