Saiba das falhas: alertas

Como os alertas funcionam

O Waiso confere as execuções terminadas a cada poucos segundos. Toda execução de script, flow ou robô do AI Scraper iniciada no nível de cima é comparada com as regras ativas do projeto; um agendamento que estava na hora e não conseguiu iniciar também conta. Uma correspondência vira uma mensagem em cada canal da regra — no máximo uma por canal por evento, quantas regras combinarem.

A mensagem traz o item, a primeira linha do erro, o passo que falhou num flow, o que iniciou a execução (um agendamento, um token de API, um gatilho de evento) e um link para ela — nunca as entradas, as saídas ou as variáveis. Os passos de um flow alertam como o flow, não um a um, e uma execução cancelada nunca alerta.

Adicione um canal

1. 1
   Onde

   Em Alertas, abra Canais e clique em Adicionar canal (numa página vazia, Adicionar canal no centro). Para onde vão os alertas? — Slack, Microsoft Teams, Discord, E-mail ou Webhook. O tipo não muda depois de salvo.

   Adicionar canal
2. 2
   Detalhes

   Dê um Nome e o endereço. Slack: a URL de um Incoming Webhook. Teams: a URL de um webhook do Workflows. Discord: configurações do canal → Integrações → Webhooks. E-mail: os endereços em Enviar para, enviados pelo provedor de e-mail do projeto. Webhook: qualquer endereço https:// público. As URLs ficam criptografadas e nunca mais aparecem.

3. 3
   Salve e teste

   Clique em Salvar canal e depois em Enviar teste na linha dele: Teste entregue em #ops-alerts. — ou o motivo de não ter sido. Num webhook, a etapa seguinte mostra o segredo de assinatura uma única vez: copie e clique em Já copiei.

Crie uma regra

Em Regras, clique em Nova regra. O assistente tem quatro etapas — O quê, Quando, Onde, Revisar — e dá para voltar a qualquer uma.

Cada regra tem um botão Ativa na linha; uma regra pausada não envia nada. Excluir um canal usado por regras pausa toda regra que ficar sem canal, e a página diz quantas.

Agrupamento e Voltou a funcionar

A primeira falha de um item alerta na hora (Falhou: nightly-import). As falhas seguintes do mesmo item são contadas, e no máximo uma vez por janela de agrupamento sai um aviso — Ainda falhando: nightly-import falhou mais 7 vezes desde o último alerta. A primeira execução boa depois das falhas envia Voltou a funcionar, com quanto tempo ficou quebrado. Assim um agendamento que falha a cada minuto a noite toda vira poucas mensagens, não centenas.

Histórico e saúde de entrega

Histórico lista cada mensagem com o tipo (Falhou, Continua falhando, Voltou a funcionar, Não iniciou, Teste, Resumo), o status (Entregue, Enviando, Falhou, No resumo) e Abrir execução. Uma entrega que falha é tentada de novo após 30, 90 e 180 segundos. Cada canal mostra a saúde de entrega: Ainda não usado, Entregando, Última tentativa falhou ou Não entrega depois de as três últimas entregas falharem — o painel Visão geral conta esses.

O canal webhook

Um canal webhook recebe um POST JSON por mensagem, assinado com X-Waiso-Signature: t=<segundos unix>,v1=<hex>, onde v1 é hmac_sha256(segredo, "<t>.<corpo>") sobre o corpo bruto. Confira antes de confiar na chamada, e recuse carimbos de tempo antigos para que uma requisição capturada não possa ser repetida.

{
  "type": "failed",
  "project": {
    "id": "p_7Hq2…",
    "name": "Reports"
  },
  "item": {
    "kind": "script",
    "id": "…",
    "name": "nightly-import"
  },
  "error": "RuntimeError: the upstream file was empty",
  "step": null,
  "startedBy": "schedule 'nightly'",
  "count": 1,
  "brokenForSeconds": null,
  "runId": "…",
  "runUrl": "https://<your-waiso-address>/projects/reports/runs?run=…",
  "at": "2026-10-16T03:00:04Z"
}

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, max_age: int = 300) -> bool:
    """header = the X-Waiso-Signature value: "t=1760000000,v1=ab12…"."""
    parts = dict(item.split("=", 1) for item in header.split(","))
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > max_age:
        return False                      # too old: a replayed request
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Limites

• Os endereços de webhook precisam ser URLs https:// públicas (Esse endereço não é permitido: use uma URL https:// pública.). Cada envio é conferido de novo, redirecionamentos não são seguidos e um envio expira em 10 segundos.
• Um canal envia no máximo 20 mensagens por minuto; o restante daquele minuto vira um único resumo E mais 12 alertas neste minuto.
• Um canal de e-mail precisa do provedor de e-mail do projeto (Adicione um em Integrações → E-mail.).
• Só admins e quem criou o projeto podem mudar os alertas.