POST com o payload do evento na URL configurada, assinado com HMAC-SHA256.
A configuração do webhook é feita exclusivamente pelo sistema (interface web). Não há endpoint de API para criar ou alterar a configuração do webhook.
Configuração (pelo sistema)
Acesse a aba Webhook do canal
No painel, vá em Dashboard → Suporte → Canais, escolha o canal, abra Configurações e selecione a aba Webhook.
Ative e informe a URL
Habilite o webhook e informe a URL de destino (
http:// ou https://). Recomendado: HTTPS.Gere o secret
Clique em Gerar secret. Ele é exibido uma única vez — guarde-o para validar a assinatura das entregas. Gerar um novo secret invalida o anterior.
Eventos
Hoje existem dois eventos de negócio que geram entrega, mais o ping de teste:| Evento | Descrição |
|---|---|
message_received | Mensagem recebida de um contato no canal |
message_sent | Mensagem enviada pelo canal (agente, bot ou API) |
webhook.test | Disparado manualmente pelo botão de teste na aba Webhook |
A interface permite marcar outros eventos na seleção (
chat_created, chat_closed, chat_transferred, chat_assigned), mas eles ainda não geram entregas — não há disparo implementado para esses eventos no backend hoje. Marcá-los não tem efeito prático.Configurações criadas antes da seleção de eventos existir (sem lista de eventos salva) recebem todos os eventos suportados, por compatibilidade.
Verificação de assinatura
Toda entrega inclui dois headers:| Header | Conteúdo |
|---|---|
X-Webhook-Signature | sha256=<hex> — HMAC-SHA256 do texto "{timestamp}.{body}" usando o secret do canal |
X-Webhook-Timestamp | Timestamp da assinatura em milissegundos (epoch) |
X-Webhook-Timestamp, um ponto (.) e o corpo bruto da requisição, calcule o HMAC-SHA256 com o secret e compare com o valor após sha256=.
Entrega, timeout e retries
- Sucesso: qualquer resposta
2xx. Responda rápido (idealmente200imediato) e processe o evento de forma assíncrona. - Timeout: 10 segundos por tentativa.
- Retries automáticos: até 5 tentativas com backoff exponencial (2s, 4s, 8s, 16s entre as tentativas seguintes) para erros de rede, respostas
5xxe429. - Sem retry: respostas
4xx(exceto429) não são retentadas — normalmente indicam URL ou secret mal configurados no destino. - Reenvio manual: entregas com falha podem ser reenviadas pela aba Webhook do canal (histórico de entregas → reenviar).