Alertas

Um alerta avisa você quando seus workflows se comportam de um jeito que você quer acompanhar: falhas repetidas, uma execução lenta, uma execução cara demais ou nenhuma atividade. Você configura o alerta uma vez no workspace, escolhe a condição que o 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 limites.

As regras baseadas em taxa (failure rate, latency spike) precisam de pelo menos 5 execuções na janela antes de serem avaliadas. A regra de inatividade é verificada por uma consulta em segundo plano, não a cada execução. Depois que um alerta dispara, ele fica em silêncio por 1 hora, para que um único problema não inunde você de avisos.

Você pode limitar 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 até você de três formas:

• Webhook envia um payload JSON assinado para uma URL que você informa.
• Email envia para uma lista de até 10 destinatários.
• Slack publica em um canal através de uma conta do Slack conectada.

Payload do webhook

Um alerta por webhook é um HTTP POST com um 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, seus traceSpans (só em webhook), o status de rate limit e os dados de uso, ativando essas opções no alerta.

Verificando um webhook

Cada entrega é assinada para você confirmar que veio do Studio. A assinatura está no header studio-signature:

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

Para verificar, calcule um HMAC-SHA256 sobre {t}.{raw_body} usando o secret do seu 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 Studio também envia os headers studio-event, studio-timestamp e Idempotency-Key em cada entrega, para que o receptor possa descartar retentativas duplicadas.

Retentativas

Se o seu endpoint não retornar um 2xx, o Studio tenta novamente até 5 vezes, com intervalos crescentes de 5s, 15s, 60s, 3m e 10m, cada um com um pouco de jitter. Após a quinta falha, a entrega é marcada como falha.

Configurando um alerta

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

• GET /api/workspaces/{id}/notifications lista os alertas.
• POST /api/workspaces/{id}/notifications cria um alerta.
• PUT /api/workspaces/{id}/notifications/{notificationId} atualiza um alerta.
• DELETE /api/workspaces/{id}/notifications/{notificationId} remove um alerta.
• 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