Buscar K
Aparência
Configurar o webhook
- Tipo
- Como fazer
- Para
- Administrador do Tenant, Desenvolvedor
- Na tela
- HEC › Tenants › Avançado › Canais de Alerta
O canal Webhook entrega o alerta como um POST JSON numa URL HTTPS sua, para outro sistema tratar: abrir chamado, gravar log, repassar para um chat interno. A URL é uma só por Tenant e vale para todos os alertas dele que marcarem o canal.
Ligar o canal
- No HEC, abra o Tenant e vá em Avançado › Canais de Alerta.
- Em Canais de envio de alertas disponíveis, marque Webhook.
- Preencha URL do Webhook.
- Se o receptor exige autenticação, adicione os cabeçalhos em Headers HTTP Customizados › Adicionar Header, como
X-Auth-Token: <segredo>. - Salve o Tenant.
- No alerta, marque Webhook em Canais de Envio do Alerta.
O Cliente tem os mesmos campos. Um Tenant com a URL vazia usa a URL do Cliente dele, mas os cabeçalhos continuam sendo os do Tenant: cadastre a autenticação no Tenant também.
Para testar sem servidor próprio, use uma URL temporária de um serviço de inspeção de requisições e dispare o alerta com Forçar Envio (veja receber o webhook).
Regras da URL
A URL é validada ao salvar. No envio, o Lumo só confere se ela ainda começa com https://.
| Regra | Mensagem quando falha |
|---|---|
Começa com https:// | A URL do webhook precisa usar https. |
| Porta 443 (a padrão) | A URL do webhook precisa usar a porta 443 (recebida: <porta>). |
Sem usuário e senha na URL (https://user:pass@...) | A URL do webhook não pode conter usuário e senha. |
Endereço público. IP privado, localhost e nomes terminados em .local ou .internal são recusados | A URL do webhook não pode apontar para um endereço de rede interna. |
| Endereço que dá para interpretar | A URL do webhook é inválida. |
Credencial vai em cabeçalho, nunca na URL.
Cabeçalhos
| Regra | Valor |
|---|---|
| Quantidade | Até 20 |
| Nome | Até 100 caracteres: letras, dígitos e ! # $ % & ' * + - . ^ _ ` | ~. Sem nome repetido, sem diferenciar maiúscula de minúscula |
| Valor | Até 500 caracteres |
| Reservados | Content-Type, User-Agent, Host, Content-Length e Connection não podem ser sobrescritos |
Linha com erro fica vermelha no editor e é descartada ao salvar o Tenant, sem impedir o salvamento. Confira a lista depois de salvar.
Todo POST sai com Content-Type: application/json e User-Agent: Horus-Alert-Webhook/1.0, mais os cabeçalhos do Tenant.
Como o envio funciona
Cada entrega gera um POST por destinatário, com o conteúdo gerado com o acesso a dados daquela pessoa. Um alerta com 10 destinatários faz 10 POSTs. O corpo está descrito em payload.
| Item | Valor |
|---|---|
| Tempo limite por tentativa | 10 segundos |
| Tamanho máximo do corpo | 4.000.000 caracteres de JSON. Arquivos vão como links, então o limite raramente pesa |
| Sucesso | Qualquer resposta 2xx |
Repetição
Qualquer resposta fora de 2xx, incluindo 4xx, e qualquer falha de rede ou tempo limite contam como falha e disparam nova tentativa. São até 8 tentativas, com espera que dobra a cada vez, de uns 10 segundos até cerca de 2 minutos, com variação de 20% para cima ou para baixo. Do primeiro POST ao último passam de 4 a 6 minutos. Corpo acima do limite e URL sem https:// também passam pelas 8 tentativas antes de falhar.
Como o mesmo POST pode chegar mais de uma vez, o receptor precisa descartar repetições. O Lumo não manda chave de idempotência; a chave se monta com alert.id, user.id e timestamp, que não muda entre as tentativas de um mesmo POST (veja receber o webhook).
Esgotadas as 8 tentativas, a entrega fica como Falhou no histórico, e o criador do alerta e os administradores do Tenant são avisados. A falha no webhook não afeta os outros canais.