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

# Alertas e Slack

> Configure regras de alerta de ingestão e receba notificações no Slack quando algo der errado.

# Alertas e Slack

Alertas são regras configuráveis pelo usuário que avaliam a cada **30 segundos** o estado de ingestão da sua organização. Quando uma condição é satisfeita, o Atlas dispara mensagem para os canais cadastrados (Slack na v1).

## Tutorial: criar primeira regra

### 1. Crie um Incoming Webhook no Slack

No seu workspace Slack:

1. Acesse **Apps** → busque por **Incoming Webhooks** → **Add to workspace**.
2. Escolha o canal alvo (ex: `#atlas-ops`) e clique **Add Incoming Webhooks integration**.
3. Copie a **Webhook URL** que começa com `https://hooks.slack.com/services/...`. Guarde — será usada no próximo passo.

### 2. Cadastre o canal no Atlas

1. Acesse **`/dashboard/settings/alerts`** → tab **Canais** → **Adicionar canal**.
2. **Nome:** `#atlas-ops` (ou outro nome descritivo)
3. **Webhook URL:** cole a URL do passo anterior
4. **Salvar**

A URL é cifrada com **AES-256-GCM** antes de ir pro banco — nunca aparece em logs nem em respostas da API.

### 3. Teste o canal

Clique no ícone de **Enviar (paper plane)** ao lado do canal. Você deve receber uma mensagem `Atlas — teste de conexão com canal *#atlas-ops*` no Slack.

Se falhar, revise:

* URL começa com `https://hooks.slack.com/`?
* Webhook ainda está ativo no Slack workspace?
* Sua org tem firewall que bloqueia webhooks externos? (não é o caso típico)

### 4. Crie sua primeira regra

Tab **Regras** → **Nova regra**:

| Campo                | Valor sugerido                  |
| -------------------- | ------------------------------- |
| Nome                 | `Sportsbook bet_placed silence` |
| Domínio              | `sportsbook`                    |
| Evento               | `bet_placed`                    |
| Tipo de condição     | `no_data`                       |
| Threshold (segundos) | `300`                           |
| Severidade           | `critical`                      |
| Canais               | seleciona `#atlas-ops`          |

**Salvar**.

A partir do próximo tick (≤30s), o `alert_runner` começa a avaliar essa regra. Se `bet_placed` não aparecer por mais de 5 minutos, você recebe esta mensagem no Slack:

> 🚨 **ALERTA DISPARADO — Sportsbook bet\_placed silence**
>
> **Escopo:** `sportsbook` · `bet_placed`
> **Condição:** `no_data` — sem evento por mais de 5m
> **Métrica observada:** lag=8m · último ingest: 2026-05-04T11:50:32Z
> *severidade critical · regra abc123* · [abrir no Atlas](https://app.atlas.lifters.tech/dashboard/settings/alerts/abc123)

Quando a ingestão volta ao normal, uma mensagem `✅ ALERTA RESOLVIDO` é enviada automaticamente.

## Mensagem de webhook (formato Block Kit)

Atlas usa **Slack Block Kit**. Cor da attachment depende da severidade:

| Severidade | Cor (firing)       | Cor (resolved)  |
| ---------- | ------------------ | --------------- |
| `info`     | cinza `#A0A0A0`    | verde `#3BA776` |
| `warning`  | laranja `#F26122`  | verde `#3BA776` |
| `critical` | vermelho `#E54848` | verde `#3BA776` |

## Cooldown

Para evitar flood quando uma condição persiste, cada regra tem `cooldown_seconds` (default **300**). Após disparo, a regra não re-dispara até cessar OU passar o cooldown.

## Notificação in-app

Além do Slack, todo disparo cria uma row em `notifications` (tabela existente da plataforma). O **bell icon** do dashboard mostra os últimos 20 disparos com:

* Severidade
* Nome da regra
* Estado (firing/resolved)
* Link pra editar a regra

## Endpoints REST

A UI cobre 99% dos casos, mas os endpoints estão disponíveis para automação:

```
POST   /v1/alerts/channels        # cadastrar Slack webhook
GET    /v1/alerts/channels        # listar
POST   /v1/alerts/channels/{id}/test  # ping de teste
DELETE /v1/alerts/channels/{id}

POST   /v1/alerts/rules           # criar regra
GET    /v1/alerts/rules           # listar
PATCH  /v1/alerts/rules/{id}      # editar
DELETE /v1/alerts/rules/{id}

GET    /v1/alerts/events          # histórico de disparos
GET    /v1/alerts/events/{id}     # detalhe
```

Body para criar canal Slack:

```json theme={null}
{
  "type": "slack",
  "name": "#atlas-ops",
  "config": { "webhook_url": "https://hooks.slack.com/services/T/B/X" }
}
```

Body para criar regra `no_data`:

```json theme={null}
{
  "name": "Sportsbook bet_placed silence",
  "domain": "sportsbook",
  "event": "bet_placed",
  "condition_type": "no_data",
  "threshold_seconds": 300,
  "severity": "critical",
  "channel_ids": ["channel_uuid"]
}
```

## Limitações conhecidas v1

* **Apenas Slack** como canal externo. WhatsApp / e-mail / webhook genérico estão no roadmap v2.
* **Apenas Incoming Webhook** (URL fixa por canal). Slack OAuth App (escolher canal dinâmico por regra) é v2.
* **Sem RBAC visual** — qualquer membro autenticado da org pode criar/editar/excluir alertas.
* **Sem snooze/acknowledge** — ack via UI fica em v2.
* **Sem schedule de "horário de silêncio"** (ex: pausar entre 23h-06h).
* **Mensagens em pt-BR hardcoded.** Multi-idioma em v2.