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

# Monitoring & Alerts

Alert rules, notification channels, issue tracking, and auto-resolve behavior.

Hookstream turns delivery problems into actionable signal through three connected pieces: **issues** (auto-detected problems), **alert rules** (configurable triggers over metrics), and **notification channels** (where alerts go). A cron runs every 5 minutes evaluating every rule and sending notifications.

## Issues: auto-detected problems

Issues are created automatically when something breaks:

- A delivery fails after all retries are exhausted.
- A destination's [circuit breaker](/guides/circuit-breaker) opens.
- Error rate crosses an internal threshold.

Each issue tracks severity, affected source/destination, failure count, and a timeline of related attempts. Issues auto-resolve after **30 minutes** of no new matching failures — or you can manually resolve them with `PATCH /v1/issues/:id`.

## Alert rule types

Hookstream supports five alert types. Each takes a `rule_config` with thresholds specific to the type.

| Type | Triggers when | `rule_config` |
| --- | --- | --- |
| `failure_rate` | Delivery failure rate exceeds a percentage over the evaluation window. | `{ "threshold": 10 }` |
| `latency` | p95 delivery latency exceeds a millisecond threshold. | `{ "threshold": 2000 }` |
| `volume_drop` | Event volume drops below a threshold vs the previous window. | `{ "threshold": 50 }` |
| `dlq` | DLQ event count exceeds a number. | `{ "threshold": 5 }` |
| `issue_opened` | A new issue is created. | `{}` |

## Create an alert rule

**Create a notification channel**

Hookstream supports two channel types: **webhook** (HTTP POST to a URL, optionally HMAC-signed) and **email** (delivered via Resend).

    ```bash webhook
    curl -X POST https://hookstream.io/v1/notification-channels \
      -H "X-API-Key: $HOOKSTREAM_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Ops Webhook",
        "channel_type": "webhook",
        "config": {
          "url": "https://ops.example.com/alerts",
          "secret": "optional_hmac_secret"
        }
      }'
    ```

    ```bash email
    curl -X POST https://hookstream.io/v1/notification-channels \
      -H "X-API-Key: $HOOKSTREAM_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Team Email",
        "channel_type": "email",
        "config": { "to": "oncall@example.com" }
      }'
    ```

    Webhook notifications include an `X-hookstream-Signature` header (HMAC-SHA256) when `secret` is set. Test any channel with `POST /v1/notification-channels/:id/test`.
  **Create an alert rule**

Link one or more channels to the rule and set a cooldown so you don't get paged 50 times in a row:

    ```bash
    curl -X POST https://hookstream.io/v1/alert-rules \
      -H "X-API-Key: $HOOKSTREAM_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "High Failure Rate",
        "rule_type": "failure_rate",
        "rule_config": { "threshold": 10 },
        "channel_ids": ["ch_abc"],
        "cooldown_minutes": 60
      }'
    ```
  **Wait (up to 5 minutes) or force an eval**

The cron runs every 5 minutes. For testing, tripping the rule intentionally (post some failing deliveries) and waiting a cycle is the fastest way to confirm it works end to end.

## Auto-resolve

Open issues and fired alerts auto-resolve after 30 minutes without a matching event. The same 5-minute cron that evaluates rules also closes stable issues. If you need immediate resolution, `PATCH /v1/issues/:id` with `status: "resolved"`.

## Troubleshooting

**My alert never fires**

Rules are gated by `cooldown_minutes` — if it fired recently, it won't fire again until the cooldown expires. Also check `rule_config.threshold` is lower than current actual values, and that the rule is `enabled`.
  **Webhook notifications return 401 on my server**

If you set `config.secret`, you need to verify the `X-hookstream-Signature` header on your side. See [Outbound Signing](/guides/outbound-signing) for a receiver verification snippet — the algorithm is the same.
  **I'm getting duplicate notifications**

Each rule dedupes via its cooldown, but multiple rules can fire on the same underlying event (e.g. both `failure_rate` and `issue_opened`). That's intentional — if you want one-signal-per-incident, pick a single rule and disable the rest.

## Next Steps

**[Alert Rules API](/api/alert-rules)**

Full schema for rule types and configs.
  **[Notification Channels API](/api/notification-channels)**

Channel schema and the test endpoint.