Webhooks

Os webhooks permitem que você receba notificações em tempo real quando eventos acontecem no seu workspace.

Criando um Webhook

1. Acesse Configurações → Gerenciar Webhooks
2. Clique em Registrar Webhook
3. Insira a URL para onde as notificações devem ser enviadas
4. Opcionalmente adicione um segredo para verificação de assinatura
5. Clique em Criar

Tipos de Evento

Os webhooks são disparados para estes eventos:

Evento	Quando é Disparado
ingestion.completed	Um job de ingestão de dados é concluído
ingestion.failed	Um job de ingestão de dados falha
kpi.computed	Um valor de KPI é calculado
kpi.alert	Uma anomalia de KPI é detectada
analysis.completed	Uma investigação é concluída
dashboard.ready	A construção de um dashboard é concluída

Formato do Payload

{
  "event": "ingestion.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "tenantId": "tenant_abc123",
  "data": {
    "jobId": "job_xyz",
    "table": "sales_data",
    "rowsIngested": 15234,
    "duration": 3200
  }
}

Verificação de Assinatura

Se você configurou um segredo, cada webhook inclui um cabeçalho X-Webhook-Signature com uma assinatura HMAC-SHA256 do corpo:

X-Webhook-Signature: sha256=abc123...

Verifique no seu serviço:

const crypto = require('crypto')
const signature = crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(requestBody)
  .digest('hex')
const isValid = signature === receivedSignature

Gerenciando Webhooks

Ações

Ação	Descrição
Testar	Enviar um evento de teste para verificar a conectividade
Histórico de Entregas	Visualizar entregas anteriores com códigos de status e timestamps
Excluir	Remover o webhook

Histórico de Entregas

Cada entrega mostra:

• Código de status — 200 = sucesso, outro = falha
• Timestamp — Quando o evento foi enviado
• Tempo de resposta — Quanto tempo seu servidor levou para responder
• Reenviar — Reenviar um evento específico

Fila de Mensagens Mortas (DLQ)

Entregas com falha vão para a Fila de Mensagens Mortas após múltiplas tentativas de reenvio. A partir da DLQ você pode:

• Visualizar eventos com falha e suas mensagens de erro
• Reprocessar eventos individuais
• Reprocessar Todos para tentar novamente todos os eventos com falha

info

Política de retentativa: Entregas com falha são retentadas até 3 vezes com backoff exponencial (1min, 5min, 15min). Após todas as tentativas falharem, o evento vai para a DLQ.