Webhook de saída
O webhook é o Hugi chamando o seu endereço quando algo acontece: o cliente escreveu, a sua mensagem foi entregue, uma conversa abriu ou foi encerrada.
Integrações e API → Webhook de saída.
Os eventos #
| Evento | Quando |
|---|---|
mensagem.recebida |
o cliente escreveu — com contato, conversa, protocolo e, havendo anexo, o endereço para baixar |
mensagem.recibo |
o que você enviou foi aceito, entregue, lido ou falhou |
mensagem.transcrita |
o texto de um áudio ficou pronto (ou o motor desistiu) |
atendimento.aberto |
uma conversa nova entrou |
atendimento.finalizado |
uma conversa foi encerrada, com motivo e os dois tempos separados |
No cadastro você marca quais quer. Não marcar nenhum significa todos, inclusive os que ainda vamos criar — é o padrão, e é o certo para o primeiro endpoint: receber demais é ruído que o seu código ignora; receber de menos é um evento que ninguém percebe que está faltando.
Detalhe de cada um, com exemplo, em A API do Hugi.
Cadastrar #
Informe a URL — https://seu-sistema.com.br/webhooks/hugi — e guarde o segredo deste
endpoint, que a tela mostra. Ele é o que assina cada chamada.
A tela lista as tentativas, com status e latência de cada uma. É por ali que se descobre que o endpoint respondeu 500 a noite inteira.
Conferir a assinatura #
Cada chamada leva o cabeçalho:
x-hugi-signature-256: <HMAC-SHA256 do corpo, com o seu segredo>
Confira sempre. Um endpoint que aceita qualquer POST aceita o POST de qualquer um.
Compare em tempo constante — no Node, timingSafeEqual —, e confira o tamanho antes, porque
essa função lança exceção com tamanhos diferentes. A tela tem o trecho de código pronto, em
Como verificar a assinatura no seu código.
O que conta como entrega bem-sucedida #
Só 2xx.
3xx é falha. Redirecionamento não é seguido de propósito: seguir mandaria um corpo assinado
para um endereço que você não cadastrou, e um redirecionamento aberto no seu domínio viraria uma
forma de desviar os seus próprios dados. Se a sua URL mudou, mude o cadastro.
Falha entra na fila de repetição, e cada tentativa aparece no log.
Correlação #
O recibo traz de volta a correlacao que você mandou no envio pela
API. É ela que liga “o pedido 4821” à mensagem que chegou — ou não chegou — no
telefone do cliente.
Desativar #
O cadastro tem um interruptor Ativo / Desativado. Desativar para de entregar sem apagar o endpoint nem o histórico de tentativas — útil enquanto o seu sistema está em manutenção.