Alertas

Um alerta avisa quando seus workflows se comportam de um jeito que você quer saber: falhas repetidas, uma execução lenta, uma execução cara ou nenhuma atividade. Você configura um alerta uma vez no workspace, escolhe a condição que dispara e define como quer ser avisado.

Regras de alerta

Uma regra de alerta é a condição que dispara o alerta. Cada alerta tem uma regra, configurada com seus próprios limiares.

As regras baseadas em taxa (failure rate, latency spike) precisam de pelo menos 5 execuções na janela antes de avaliar. No-activity é checado por um poll em background, não a cada execução. Depois que um alerta dispara, ele fica quieto por 1 hora para um único problema não te inundar.

Você pode restringir uma regra a todos os workflows ou a workflows específicos, e filtrar por nível (info ou error) e por tipo de trigger.

Canais de entrega

Um alerta pode chegar de três formas:

• Webhook envia um payload JSON assinado para uma URL que você fornece.
• Email envia para uma lista de destinatários, até 10.
• Slack publica em um canal por meio de uma conta Slack conectada.

Payload do webhook

Um alerta por webhook é um HTTP POST com corpo JSON:

{
  "id": "evt_...",
  "type": "workflow.execution.completed",
  "timestamp": 1719907200000,
  "data": {
    "workflowId": "wf_...",
    "workflowName": "Lead scorer",
    "executionId": "exec_...",
    "status": "error",
    "level": "error",
    "trigger": "api",
    "startedAt": "2026-06-01T12:00:00.000Z",
    "endedAt": "2026-06-01T12:00:01.200Z",
    "totalDurationMs": 1200,
    "cost": { "total": 0.0042 }
  }
}

Você também pode incluir o finalOutput da execução, os traceSpans (só webhook), status de rate-limit e dados de uso ativando essas opções no alerta.

Verificando um webhook

Cada entrega é assinada para você confirmar que veio do Zoen. A assinatura fica no header sim-signature:

sim-signature: t=1719907200000,v1=<hex>

Para verificar, calcule um HMAC-SHA256 sobre {t}.{raw_body} com o segredo do webhook e compare o resultado com v1:

import { createHmac } from 'node:crypto'

function verify(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')))
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return expected === parts.v1
}

O Zoen também envia os headers sim-event, sim-timestamp e Idempotency-Key em cada entrega, para o receptor deduplicar retries.

Retries

Se o seu endpoint não devolver um 2xx, o Zoen tenta de novo até 5 vezes com atrasos crescentes de 5s, 15s, 60s, 3m e depois 10m, cada um com um pouco de jitter. Depois da quinta falha a entrega é marcada como failed.

Configurando um alerta

Configure alertas nas configurações de notificação do workspace, ou pela API de notificações do workspace:

• GET /api/workspaces/{id}/notifications lista alertas.
• POST /api/workspaces/{id}/notifications cria um.
• PUT /api/workspaces/{id}/notifications/{notificationId} atualiza um.
• DELETE /api/workspaces/{id}/notifications/{notificationId} remove um.
• POST /api/workspaces/{id}/notifications/{notificationId}/test envia um teste.

Criar ou alterar um alerta exige acesso Write ou Admin ao workspace. Um workspace pode ter até 10 alertas de cada tipo de canal.

Próximos passos