> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arguserror.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Alert Rules in Argus

> Create alert rules to receive email or webhook notifications the moment Argus detects a new issue in your project.

Alert rules let you get notified immediately when something goes wrong in your application — without having to check the dashboard manually. Argus supports two rule types: **new issue** (fires the first time a distinct error appears) and **error rate** (fires when events cross a threshold within a time window). When a rule matches, Argus fires every configured notification channel within seconds. Configure an email address, a webhook endpoint, or both, and Argus handles the delivery.

## Alert rule fields

When you create an alert rule, you configure the following fields:

| Field             | Type     | Required             | Description                                                                                                                                  |
| ----------------- | -------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | string   | ✅                    | A human-readable label for this rule, e.g. `"Production errors"`                                                                             |
| `type`            | enum     | —                    | `NEW_ISSUE` (default) fires when a new distinct issue is created. `ERROR_RATE` fires when event volume crosses a threshold in a time window. |
| `threshold`       | number   | `ERROR_RATE`         | Event count that triggers an error-rate rule within its window.                                                                              |
| `windowMinutes`   | number   | `ERROR_RATE`         | Rolling time window (minutes) an error-rate rule counts events over.                                                                         |
| `notifyEmail`     | string   | ✅ (or `webhookUrl`)  | Email address to send a notification to when the rule fires                                                                                  |
| `webhookUrl`      | string   | ✅ (or `notifyEmail`) | URL that receives a `POST` request when the rule fires                                                                                       |
| `enabled`         | boolean  | —                    | Defaults to `true`. Set to `false` to pause the rule without deleting it.                                                                    |
| `lastTriggeredAt` | datetime | —                    | Timestamp of the most recent time this rule fired a notification. Read-only.                                                                 |

<Note>
  You must supply at least one of `notifyEmail` or `webhookUrl` — a rule with neither delivery channel is rejected with a validation error. You can supply both to notify via two channels simultaneously.
</Note>

## Alert types

**New issue (`NEW_ISSUE`)** — fires the first time Argus sees a given error fingerprint in your project (when a brand-new issue is created). Naturally deduplicated: each distinct issue alerts once.

**Error rate (`ERROR_RATE`)** — fires when the number of events in your project crosses `threshold` within the last `windowMinutes`. To avoid noise, a rule that has fired won't fire again until one full window has elapsed (a cooldown), so a sustained spike alerts **once** rather than on every event.

## Creating an alert

<Steps>
  <Step title="Open the Alerts page">
    Navigate to your project in the Argus dashboard and click **Alerts** in the sidebar.
  </Step>

  <Step title="Click New Rule">
    Click the **New rule** button in the top-right corner of the Alerts page. The alert rule modal opens.
  </Step>

  <Step title="Name your rule and choose a type">
    Enter a descriptive name, then pick a **type**: **New issue** to fire on every brand-new issue, or **Error rate** to fire on a spike.
  </Step>

  <Step title="Set a threshold (error-rate rules only)">
    If you chose **Error rate**, set the **threshold** (event count) and **window** (minutes) — for example, 100 events in 5 minutes.
  </Step>

  <Step title="Add a delivery channel">
    Enter an **email address**, a **webhook URL**, or both. Argus requires at least one.
  </Step>

  <Step title="Save the rule">
    Click **Save**. The rule is active immediately — the next new issue to arrive will trigger a notification.
  </Step>
</Steps>

## Webhook payload

When a rule fires, Argus sends an HTTP `POST` with a JSON body to your `webhookUrl`. The `type` field tells you which kind of alert fired. Use this to integrate with Slack (via incoming webhooks), PagerDuty, or any custom pipeline you operate.

**New issue:**

```json theme={null}
{
  "type": "new_issue",
  "projectName": "my-shop",
  "issue": {
    "id": "clx1234abcd",
    "title": "TypeError: Cannot read properties of undefined",
    "culprit": "src/api/users.ts:42",
    "level": "ERROR",
    "status": "UNRESOLVED",
    "eventCount": 1,
    "firstSeen": "2026-07-03T09:14:55.000Z",
    "projectId": "clx0000proj"
  },
  "issueUrl": "https://app.argus.dev/projects/clx0000proj/issues/clx1234abcd"
}
```

**Error rate:**

```json theme={null}
{
  "type": "error_rate",
  "projectName": "my-shop",
  "count": 128,
  "threshold": 100,
  "windowMinutes": 5,
  "issuesUrl": "https://app.argus.dev/projects/clx0000proj/issues"
}
```

Your endpoint should respond with a `2xx` status code to acknowledge receipt. Argus records the outcome of every delivery attempt in the alert log (see [Alert logs](#alert-logs) below).

## Email notifications

When a rule fires an email, Argus delivers a notification to the configured address. New-issue emails include the issue title, level, culprit, and a direct link to the issue; error-rate emails include the event count, threshold, and window, with a link to the project's issues.

Make sure the email address you configure is deliverable — Argus does not verify addresses at rule creation time.

## Managing rules

From the **Alerts** page you can:

* **Edit** a rule — click the pencil icon on any rule card to update its name, delivery channel, or enabled state.
* **Toggle enabled** — click the toggle switch on a rule card to pause or resume it without deleting it. Paused rules appear dimmed.
* **Delete** a rule — click the trash icon to permanently remove the rule and all of its logs.

You can also manage rules programmatically via the REST API:

```http theme={null}
# List all rules for a project
GET /api/v1/projects/:projectId/alerts

# Create a new rule
POST /api/v1/projects/:projectId/alerts

# Update an existing rule
PATCH /api/v1/projects/:projectId/alerts/:id

# Delete a rule
DELETE /api/v1/projects/:projectId/alerts/:id
```

## Alert logs

Every delivery attempt — whether successful or failed — is recorded in the **alert log**. Each log entry captures:

* Which alert rule fired
* Which channel was used (`email` or `webhook`)
* The target address or URL
* Whether delivery succeeded
* Any error message if delivery failed
* The timestamp the alert was triggered

View logs directly in the dashboard by opening any alert rule. Use logs to diagnose failed webhook deliveries or to confirm that a notification was sent for a specific issue.

<Tip>
  Use multiple alert rules to route notifications by severity. For example, create one rule that sends a webhook to your on-call channel for all new issues, and a separate rule with a different email address to notify a specific team member. Combine this with issue-level filters in your downstream tooling to triage by priority.
</Tip>

For the full list of alert endpoints, see the [Alerts API reference](/api/alerts).