> ## 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.

<Warning>
  Alerts require the **Pro** plan or higher.
</Warning>

## Creating an alert rule

Go to **Alerts** and click **Create Alert**.

<Steps>
  <Step title="Name the rule">
    Give it a descriptive name — e.g. `High error rate — support agent` or `Cost spike — prod`.
  </Step>

  <Step title="Choose a metric">
    | 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.
  </Step>

  <Step title="Set condition and threshold">
    Choose an operator (`>`, `<`, `>=`, `<=`) and the threshold value.

    Example: `error_rate > 0.05` fires when more than 5% of operations fail.
  </Step>

  <Step title="Set the evaluation window">
    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              |
  </Step>

  <Step title="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](/guides/webhooks) for the schema and signature verification.

    Use **Test channel** after adding a channel to verify delivery before the rule goes live.
  </Step>
</Steps>

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.