# Alerts & notification channels

> https://docs.errora.org/en/products/alerts

Alerts are two objects: a **channel** (where a message goes) and an **alert rule** (which
event sends one). Both live in **Settings → Webhooks**.

## Event types you can subscribe to

| Event | Fires when |
| --- | --- |
| `issue.created` | A new unique exception type appears |
| `event.received` | Any exception event arrives (noisy — scope it) |
| `issue.regressed` | A resolved issue comes back |
| `autofix.started` | An [AI auto-fix](/en/products/ai-autofix) run starts |
| `autofix.mr_created` | Auto-fix opened a merge request |
| `autofix.failed` | Auto-fix failed |
| `monitor.failed` | A [cron monitor](/en/products/crons) is failing |
| `monitor.recovered` | A cron monitor recovered |
| `uptime.down` | An [uptime monitor](/en/products/uptime) went down |
| `uptime.up` | An uptime monitor recovered |
| `feedback.received` | New [user feedback](/en/products/user-feedback) arrived |
| `wallet.balance_low` | The [wallet](/en/billing/wallet) crossed a threshold you set |

## Channel types

| Type | What it needs |
| --- | --- |
| `webhook` | A URL. Errora `POST`s your rendered template as the body. |
| `mattermost` | An incoming-webhook URL |
| `telegram` | A connected chat (see below) — **no bot token needed** |
| `bale` | A connected chat (see below) |
| `email` | A recipient address |
| `sms` | A mobile number, delivered through the configured SMS provider |

### Telegram and Bale — connecting a chat

Errora runs its own Telegram and Bale bots, so you never create or paste a bot token:

1. **Settings → Webhooks → Connect a Telegram/Bale chat.** Errora issues a short-lived
   deep link.
2. Open the link and press **Start**. The chat is now linked to your organization.
3. Create a channel of that type and pick the connected chat.

Chats are linked per organization: a channel can only send to a chat that was connected from
the same organization.

## Templates

Every channel takes an optional template using `{{ placeholder }}` tokens. Unknown tokens
render as empty strings.

Available placeholders: `{{ event }}`, `{{ title }}`, `{{ body }}`, `{{ url }}`,
`{{ level }}`, `{{ issue_id }}`.

Defaults per channel type:

```text
webhook      {"event": "{{ event }}", "title": "{{ title }}", "body": "{{ body }}",
              "url": "{{ url }}", "level": "{{ level }}", "issue_id": "{{ issue_id }}"}
mattermost   **{{ title }}**\n{{ body }}\n[View in Errora]({{ url }})
telegram     {{ title }}\n{{ body }}\n{{ url }}
bale         {{ title }}\n{{ body }}\n{{ url }}
email        {{ body }}\n\n{{ url }}
sms          Errora: {{ title }}
```

Two things make templates safe to edit:

- **Live preview** renders your template exactly the way a real notification will render it.
- **Send test** delivers a sample notification right now and shows you the provider's own
  answer, so a wrong webhook URL or a disconnected chat fails loudly instead of silently.

## Alert rules

A rule ties an **event type** to a **channel**, optionally scoped to a project. Create one
per (event, channel) pair you want.

```bash
# 1. Create a channel
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/channels" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Ops webhook","type":"webhook","config":{"url":"https://ops.example.com/hooks/errora"}}'

# 2. Point an event at it
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/alert-rules" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"event_type":"issue.created","channel":"<channel_id>","project":"<project_id>","is_active":true}'
```

Managing channels and rules requires the **`webhook:manage`** capability.

## Wallet alerts

Balance alerts are configured on the billing page rather than here: pick a channel and a
threshold, and `wallet.balance_low` fires when the balance crosses it. See
[Wallet](/en/billing/wallet).

## Keeping the noise down

- Prefer `issue.created` over `event.received`. The second one fires for *every* event.
- Scope rules to a project; a chat that also gets staging noise gets muted by its members.
- Use cron/uptime **thresholds** so one blip doesn't page anyone.
- Send low-severity events to a webhook or Mattermost channel, and keep SMS for what must
  wake someone up.

## API

```text
GET/POST     /api/v1/organizations/{org_id}/channels
PATCH/DELETE /api/v1/organizations/{org_id}/channels/{id}
GET          /api/v1/organizations/{org_id}/channels/template-meta
POST         /api/v1/organizations/{org_id}/channels/preview
POST         /api/v1/organizations/{org_id}/channels/{id}/test
GET/POST     /api/v1/organizations/{org_id}/alert-rules
PATCH/DELETE /api/v1/organizations/{org_id}/alert-rules/{id}
POST         /api/v1/organizations/{org_id}/chat-links/start
```

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| Test send fails | The error is the provider's own response — read it; usually a bad URL, revoked token, or an unconnected chat |
| Nothing arrives, test works | No alert rule for that event type, the rule is inactive, or it is scoped to a different project |
| Telegram/Bale chat not listed | The deep link expired or **Start** was never pressed — issue a new link |
| Email not delivered | Check the address, and your spam folder |
| SMS not delivered | Check the number is a valid Iranian mobile |
| Too many messages | You subscribed `event.received`; switch to `issue.created` |