> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Alerts
> Create threshold rules on error rate, cost, latency, and eval scores. Get notified via email, Slack, PagerDuty, OpsGenie, Discord, Jira, Freshservice, or webhook.
Alerts let you define thresholds on agent metrics and get notified the moment one is crossed. Rules are evaluated continuously against your live data.
Alerts require the **Pro** plan or higher.
## Creating an alert rule
Go to **Alerts** and click **Create Alert**.
Give it a descriptive name — e.g. `High error rate — support agent` or `Cost spike — prod`.
| Metric | What it monitors |
| ---------------- | -------------------------------------------------------------- |
| `error_rate` | Fraction of operations that fail, timeout, or are rate-limited |
| `latency` | Average response time in milliseconds |
| `cost` | Total spend in USD for the window |
| `requests` | Total operation count |
| Evaluator metric | Any custom eval score key (e.g. `quality.score`) |
To monitor a custom evaluator score, select your evaluator from the **Evaluator** dropdown and enter the metric key.
Choose an operator (`>`, `<`, `>=`, `<=`) and the threshold value.
Example: `error_rate > 0.05` fires when more than 5% of operations fail.
The window controls how far back data is aggregated before comparing to your threshold.
| Window | Best for |
| ------ | ----------------------------------------- |
| 5 min | Sudden spikes — agent errors, cost bursts |
| 15 min | Sustained error rate increases |
| 30 min | Cost trend monitoring |
| 60 min | Latency degradation patterns |
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](/guides/webhooks) for the schema and signature verification.
Use **Test channel** after adding a channel to verify delivery before the rule goes live.
Click **Create Alert** to activate. The rule is evaluated in the next cycle.
## 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.
## 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.
## Webhook payload
When a rule fires and a webhook channel is configured, Zespan POSTs:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"projectId": "proj_xyz789",
"alertName": "High error rate — support agent",
"metric": "error_rate",
"threshold": 0.05,
"currentValue": 0.12,
"severity": "critical",
"message": "error_rate is 0.12, threshold is > 0.05",
"triggeredAt": "2026-04-20T14:32:00Z"
}
```
The request includes an `X-Zespan-Signature-256` header for HMAC-SHA256 verification. See [Webhooks](/guides/webhooks) for verification code.
## Model lifecycle alerts
[Model Lifecycle](/dashboard/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.
A model-lifecycle finding is **always** recorded and visible in the dashboard (the Overview widget, the Models page Lifecycle column, and the Model lifecycle findings page) regardless of alert configuration. But email and webhook **notification** only happens if the project has at least one **enabled** alert rule of type `model-lifecycle`. With none configured, the delivery worker finds no matching rule and silently skips sending — the finding is still there, it just never reaches an inbox or a channel. If deprecation alerts seem to not be firing, this is the first thing to check.
`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](/dashboard/model-lifecycle#getting-notified) 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](/api-reference/introduction)) rather than this page's alert endpoints.
## Next steps
* [Model Lifecycle](/dashboard/model-lifecycle) — what a finding contains and the 90/30/7/0 re-raise ladder that governs when this alert type fires again
* [Incidents](/dashboard/incidents) — where a breaching alert can escalate into a tracked incident
* [Webhooks](/guides/webhooks) — full payload schema and signature verification for the webhook channel