Selo
- Motor: Determinístico (sem LLM)
- Maturidade: Preview
- Medição: Verificável por teste
1. O que faz
Avisa você quando um indicador do painel cruza um limite que você definiu — por e-mail, WhatsApp ou webhook para o seu próprio sistema. Também permite backtestar a regra antes de ligar, para saber se ela vai te encher de aviso ou nunca disparar.
2. Determinístico ou LLM?
100% determinístico. Não há LLM. A avaliação da condição, o texto do motivo, a idempotência e o webhook são código puro: avaliação da regra, simulação (backtest), idempotência/histórico de disparos e envio assinado do webhook.
Condições suportadas: >, >=, <, <= (limiar absoluto) e drop_pct/spike_pct
(queda/alta percentual vs. o snapshot anterior). Séries são resumidas por soma/média/
máx/mín/último antes da comparação. Há cooloff (janela mínima entre disparos) e rearme
por transição (o alerta só repete depois de normalizar).
3. Dados enviados e egress
- Para avaliar: nada sai — a comparação é local sobre o snapshot.
- No webhook de saída, sai um POST para a URL do SEU sistema com o payload do alerta
(dashboard/widget, regra, valor, limiar, motivo,
firedAt,idempotencyKey). Isso é egress para você, sob seu controle — não para um LLM.
4. Privacidade e retenção
- Cada disparo vira um evento de alerta escopado por workspace (nunca vaza entre workspaces),
com status de entrega (
fired/delivered/failed). - O webhook é assinado com HMAC-SHA256 (
X-Ingestia-Signature,X-Ingestia-Timestamp). O segredo é derivado por workspace (não existe em banco) e rotacionável por bump da env o segredo do webhook + redeploy. Vazamento do segredo de um workspace não compromete os demais.
5. Tokens, custo e orçamento
Não se aplica — determinístico, custo de IA zero.
6. Como ligar, quem pode usar e como desligar
- Configurado por widget (
config.alert), com canal e destino escolhidos por você. - O webhook exige uma URL válida que passe na guarda SSRF (ver abaixo).
- Rotação de segredo do webhook = mudar o segredo do webhook (a UI mostra o valor novo para você recolar no seu sistema).
7. Recusas e proteções
- Guarda SSRF no webhook: só https, sem credenciais na URL, sem
localhost/domínio interno, sem IP privado/loopback/link-local/metadata (IPv4 e IPv6, inclusive formas decimais/hex normalizadas). O POST sai da nossa rede, então destino interno é bloqueado. - Idempotência à prova de corrida: a chave é
hash(dashboardId, widgetId, hash da regra, refreshedAt do snapshot), comUNIQUEno banco — o mesmo snapshot nunca dispara a mesma regra duas vezes, mesmo com refresh reprocessado, corrida de crons ou retry. - Regra percentual sem base (primeiro refresh, sem snapshot anterior) → não dispara (não há comparação).
- Entrega com retry: 3 tentativas com backoff; 4xx (≠ 408/429) é permanente (não
re-tenta URL errada); falha final marca o evento como
failed.
8. Limitações e ausência de causalidade
- O alerta diz que um limite foi cruzado, não por quê. O motivo em português descreve
o que foi medido (ex.:
"Receita" caiu 32% vs snapshot anterior (150→102), limite 20%) — não afirma causa. - O backtest é o teto de barulho: conta em quantos pontos a condição valeria, sem simular rearme/cooloff (que só reduzem os envios). E vale o aviso de sempre: passado ≠ futuro.
- Alertas dependem do snapshot; sem refresh novo, não há reavaliação.
9. Como validar
- Idempotência: com dois refreshes do mesmo snapshot, confirme que a mesma regra dispara uma vez só (o segundo é descartado).
- Guarda SSRF: cadastre um webhook com URL interna/
http/com credencial e confirme que é rejeitada; sóhttpspara destino externo é aceito. - Backtest fiel à produção: rode o backtest da regra e confira que a contagem de disparos simulados usa a mesma condição da avaliação ao vivo.
- Verificação do lado do cliente: use o snippet de verificação fornecido para conferir a
assinatura HMAC antes de confiar no corpo, e deduplique pelo
idempotencyKey.