Webhook (Visão Geral)

O canal Webhook entrega o conteúdo de cada alerta como payload JSON numa URL que você controla. É a porta de integração entre o Lumo e o restante do seu ecossistema: sistemas internos, automações (n8n, Make, Zapier), bots de WhatsApp/Slack, gateways de mensageria customizados, lakes de auditoria, etc.

TIP

Caso real comum: o cliente quer "uma integração customizada de WhatsApp via Meta Cloud API". A forma certa de resolver é: configurar o canal Webhook, ter um middleware (servidor próprio ou n8n) que recebe o payload do Lumo e chama a API oficial da Meta. Veja exemplo completo em Avançado.

Quando usar Webhook

Integrações customizadas com sistemas internos (helpdesk, CRM, ERP, ITSM).
Automação no-code/low-code via n8n, Make, Zapier — recebe o webhook e dispara fluxos arbitrários.
Gateways de mensageria próprios (instância de WhatsApp Business API com a Meta diretamente, Slack via Incoming Webhook, Microsoft Teams, Discord, etc.).
Logs externos de auditoria (envia toda entrega para um lake/Elastic/Splunk seu).
Roteamento condicional que depende de lógica que não cabe no Lumo (ex.: priorizar pager de plantão pelo escalonamento atual).

Como funciona

Cada entrega bem-sucedida ou falha aparece no histórico do alerta com timestamps, status HTTP recebido e mensagem de erro (quando houver).

Configuração em 3 passos

1. Configurar a URL do Webhook

A URL pode ser definida em dois níveis, com herança automática:

Onde configurar	Quando usar
HEC → Tenants → [seu tenant] → Canais de Alerta Permitidos → URL do Webhook	Quando cada tenant tem destino próprio (mais comum)
HEC → Clientes → [seu cliente] → Canais de Alerta Permitidos → URL do Webhook	Quando todos os tenants do cliente devem cair no mesmo endpoint

Herança Cliente → Tenant

Se o tenant não tiver URL preenchida, o Lumo usa automaticamente a URL configurada no cliente pai. Configurar no nível do cliente é a forma mais econômica quando todos os tenants daquele cliente compartilham o mesmo middleware/integração. Para um tenant específico precisar de URL diferente, basta preencher a URL dele — ela sobrepõe a do cliente.

Requisitos da URL:

HTTPS obrigatório. URLs http:// são rejeitadas antes de qualquer tentativa de envio.
Aceita qualquer endpoint público (n8n, Make, Zapier, seu servidor, Cloudflare Worker, AWS Lambda + API Gateway, etc.).

INFO

Uma única URL atende todos os alertas do tenant (ou de todos os tenants, se configurada no cliente). Para rotear por alerta no seu lado, use o campo alert.id ou alert.nome do payload. Para rotear por destinatário, use user.id ou user.email. Para rotear por tenant quando a URL é compartilhada, use tenantId.

2. Habilitar o canal "Webhook" no alerta

No editor do alerta, aba Destinatários e Canais, marque Webhook entre os canais de entrega. Isso pode ser combinado com Email, WhatsApp e Telegram — todos recebem o mesmo conteúdo, em formatos apropriados a cada canal.

3. Testar antes de ativar

Aponte temporariamente a URL para um endpoint de teste como webhook.site (veja Receivers → webhook.site).
Use o botão Forçar envio agora no alerta para disparar uma entrega real e ver o payload chegando no endpoint de teste. (O botão Pré-visualizar apenas renderiza o conteúdo na tela — não dispara POST para a URL do webhook.)
Confira no [Histórico do alerta] o status, a resposta HTTP recebida e qualquer erro.

Contrato resumido

Aspecto	Valor
Método	`POST` (fixo)
Headers fixos (sistema)	`Content-Type: application/json`, `User-Agent: Horus-Alert-Webhook/1.0`
Headers customizados	Configuráveis por tenant (até 20, máx 100 chars na chave, 500 no valor). Veja Headers HTTP que sua URL recebe
Corpo	JSON (envelope com `alert`, `user`, `tenantId`, `timestamp`, `content[]`)
Timeout	10 segundos por tentativa
Tamanho máx. do payload	4 MB
Critério de sucesso	Status HTTP entre 200 e 299
Tentativas	Até 8 (backoff exponencial: ~2s, 4s, 8s, 16s, 32s, 1min, 2min, 4min, teto de 15min)
Jitter	±20% no intervalo de retry
Resposta armazenada	Sim, até 10 KB (truncada acima disso)
HTTP	Rejeitado (somente HTTPS)

Para a especificação completa do payload (todos os campos, JSON Schema, tipos TypeScript), veja Referência do Payload.

Preview do payload

Exemplo enxuto do que chega ao seu endpoint. Veja a referência completa para todos os campos:

json

{
  "alert": {
    "id": 123,
    "nome": "Margem Negativa Diária",
    "type": "condition",
    "app_id": 456
  },
  "user": {
    "id": 789,
    "nome": "Maria Souza",
    "email": "maria@empresa.com"
  },
  "tenantId": 1,
  "timestamp": "2026-05-27T10:30:00.000Z",
  "content": [
    {
      "id": 11,
      "type": "text",
      "nome": "Cabeçalho",
      "generated": { "text": "3 vendas com margem negativa em Loja Centro" }
    },
    {
      "id": 12,
      "type": "ai",
      "nome": "Análise IA",
      "generated": {
        "text": "Resumo: 3 vendas com prejuízo total de R$ 1.230...",
        "steps": []
      }
    },
    {
      "id": 13,
      "type": "report",
      "nome": "Detalhamento",
      "generated": {
        "pdf":  "https://storage.horusbi.com.br/download/a1b2c3.pdf",
        "xlsx": "https://storage.horusbi.com.br/download/a1b2c3.xlsx"
      }
    }
  ]
}

Confiabilidade e Reentrega

O Lumo trata seu endpoint como eventually available — falhas transitórias (timeouts, 5xx, indisponibilidade momentânea) são absorvidas pela política de retry. Mas há um teto:

Até 8 tentativas por entrega. Após esgotar, a entrega é marcada como falha permanente.
Backoff exponencial com jitter: ~2s → ~4s → ~8s → ~16s → ~32s → ~1min → ~2min → ~4min (com ±20% de variação). Teto de 15 minutos por retry, mesmo em casos extremos.
Garantia at-least-once: o mesmo payload pode chegar mais de uma vez se a sua resposta de sucesso (2xx) chegou tarde demais. Implemente idempotência (detalhes).
Falha permanente notifica o criador: quando uma entrega esgota todas as tentativas, o criador do alerta e os admins do tenant recebem uma notificação dentro do Lumo informando o problema.

WARNING

Falha no webhook não derruba outros canais. Se a mesma entrega tem Email + Webhook e o Webhook falhar permanentemente, o Email ainda foi enviado. Mas a entrega inteira aparece com status de erro no histórico (filosofia "fail loud").

Limitações conhecidas (hoje)

Para o cliente decidir antes de integrar:

Método fixo em POST. Não há PUT/PATCH/etc.
URL única por tenant. Não há URL diferente por alerta nem por destinatário.
Sem configuração de retry pelo usuário (8 tentativas e backoff são fixos).

Detalhes em Avançado → Limitações conhecidas.

INFO

Para autenticar o request no seu endpoint, combine caminho secreto na URL + headers HTTP personalizados (Authorization: Bearer ..., etc.). Veja Validação de Origem.

Próximos Passos

Referência do Payload — contrato técnico completo, JSON Schema, tipos TypeScript.
Como Receber e Testar — webhook.site, curl, n8n, Make, Zapier, Node.js, Python, serverless.
Avançado — idempotência, validação de origem, integração WhatsApp via Meta, Slack, troubleshooting, limitações.

Webhook (Visão Geral) ​

Quando usar Webhook ​

Como funciona ​

Configuração em 3 passos ​

1. Configurar a URL do Webhook ​

2. Habilitar o canal "Webhook" no alerta ​

3. Testar antes de ativar ​

Contrato resumido ​

Preview do payload ​

Confiabilidade e Reentrega ​

Limitações conhecidas (hoje) ​

Próximos Passos ​