Creating an alert rule
Go to Alerts and click Create Alert.1
Name the rule
Give it a descriptive name — e.g.
High error rate — support agent or Cost spike — prod.2
Choose a metric
error_rate, tool_error_rate, mcp_error_rate, guardrail_block_rate, truncated_rate, blocked_rate, and empty_response_rate are fractions, not percentages, so enter a threshold of 0.1 for 10%. For the last three, a threshold outside 0 to 1 is rejected with a 400.These three catch silent failures: the call succeeded, so error_rate never moves. They need at least 20 calls with a recorded finish outcome in the rule’s window; with fewer, the rule has no value and never fires. They read the finish outcome described in How a call ended, so they apply to calls recorded by an SDK or OpenTelemetry instrumentation that reports a finish reason.To monitor a custom evaluator score, select your evaluator from the Evaluator dropdown and enter the metric key.The scheduled check evaluates error_rate, latency, cost, requests and the rate metrics above on the metric you chose. Evaluator-score rules are evaluated by POST /v1/projects/{id}/alerts/evaluate, not by the scheduled check. ZespanPilot’s metric names (daily_cost, latency_p95, latency_p99, request_count, token_count) are accepted by the same evaluation.3
Set condition and threshold
Choose an operator (
>, <, >=, <=) and the threshold value.Example: error_rate > 0.05 fires when more than 5% of operations fail.4
Set the evaluation window
The window controls how far back data is aggregated before comparing to your threshold.
5
Add notification channels
Add one or more channels. You can mix channel types on a single rule.Email — enter one or more addresses (comma-separated). Receives an HTML alert with metric, current value, threshold, and a direct link to the dashboard.Slack — paste your Slack incoming webhook URL. Alert arrives as a colour-coded message (red = critical, orange = warning, blue = info).PagerDuty — paste your Events API v2 integration key. Alert triggers an incident with severity mapped to the configured level.OpsGenie — paste your OpsGenie API key. Creates an alert with priority P1/P2/P3.Discord — paste your Discord webhook URL. Alert arrives as a colour-coded embed.Jira — enter your Jira base URL, email, API token, project key, and issue type. Creates a Jira issue when the rule fires.Freshservice — enter your Freshservice domain and API key. Opens a ticket with priority mapped to severity.Webhook — paste any HTTPS URL. Zespan POSTs a signed JSON payload. See Webhooks for the schema and signature verification.Use Test channel after adding a channel to verify delivery before the rule goes live.Saved credentials are hidden. Webhook URLs and secrets, Slack and Discord URLs, PagerDuty and OpsGenie keys, and Jira and Freshservice tokens are never shown again once saved: the dashboard and API show a saved one as Saved (hidden), for every role, including viewers. Editing a rule and saving without touching a channel keeps its credential. To change one, remove the channel and add it again; to test a saved channel, add it again first (Test channel needs the credential in the form). A kept credential stays tied to its channel type and destination: changing a Jira base URL, a Freshservice domain or a webhook URL means entering the credential again.
Enabling and disabling rules
Each rule has a toggle on the rule card. Disabled rules are not evaluated and will not fire. Use this to pause a noisy rule without deleting it. Turning a rule on or off is recorded in the audit log asalert.rule_enabled or alert.rule_disabled, and creating, editing, and deleting rules are recorded too, so they all show on the Changes timeline.
Alert history
The history table shows every evaluation — both triggered and not triggered — with timestamp, rule name, metric value, and threshold. Click any row to see the full evaluation details.Editing a rule
PATCH on an alert rule recomputes the rule’s type from what it looks like after your change. Clearing the evaluator fields (no linked evaluator and a metric that doesn’t start with eval:) turns an evaluator rule back into a plain threshold rule, and linking an evaluator or an eval: metric does the reverse. Other rule types, such as model lifecycle rules, are left as they are.
Webhook payload
When a rule fires and a webhook channel is configured, Zespan POSTs:X-Zespan-Signature-256 header for HMAC-SHA256 verification. See Webhooks for verification code.
Model lifecycle alerts
Model Lifecycle uses this same alert delivery machinery — not a separate notification path — for a distinct rule type,model-lifecycle, that fires when the daily deprecation scan raises or re-raises a finding rather than on a metric threshold you configure.
AlertRule.type for this rule kind is not an option in the Create Alert flow described above, which is built around metric/threshold rules, and a model-lifecycle rule doesn’t appear in this page’s alert rules table either — both assume every rule has a metric, condition, and threshold, none of which a lifecycle rule has. Instead, it has its own small, dedicated opt-in: a settings card at the top of the Model Lifecycle page itself (toggle, notification emails, optional webhook). Enabling it there creates or updates the same AlertRule row this section describes, through a separate GET/PUT /v1/projects/{id}/model-lifecycle/alert-rule pair (see the API reference) rather than this page’s alert endpoints.
Next steps
- Model Lifecycle — what a finding contains and the 90/30/7/0 re-raise ladder that governs when this alert type fires again
- Incidents — where a breaching alert can escalate into a tracked incident
- Webhooks — full payload schema and signature verification for the webhook channel