Webhooks e eventos da UAZAPI
Consultar a API de tempos em tempos para descobrir mensagens novas atrasa a resposta e gasta requisições. A UAZAPI faz o caminho contrário: cada ocorrência selecionada na instância gera um HTTP POST com JSON para o endereço do seu sistema, com filtros que tiram da entrega as mensagens enviadas pela própria API.
Ficha e sumário da página
- Referência técnica
- UAZAPI 2.6.9
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O destino pertence ao seu sistema
A URL do webhook identifica o receptor que você mantém. Ela pode apontar para um Node Webhook no n8n ou para um endpoint do backend do seu app. A Server URL tem outra função: identifica o servidor da UAZAPI chamado pelo seu sistema. Essa diferença aparece numa investigação de falha, pois uma chamada bem-sucedida à API não prova que o servidor consegue alcançar o endereço escolhido para os eventos.
O receptor precisa aceitar a requisição enviada pela UAZAPI. Quando o endereço exige uma autenticação que o remetente não apresenta ou aponta para uma rota inexistente, o evento não chega ao processamento esperado. Você acompanha o retorno HTTP e os erros de entrega para localizar essa interrupção. Um histórico vazio no n8n pode significar que a requisição foi recusada antes de iniciar qualquer execução.
O tipo do evento define a interpretação
A assinatura seleciona as ocorrências enviadas ao receptor. O evento
messages informa mensagens, messages_update acompanha mudanças como
entrega e leitura, enquanto connection informa alterações da conexão.
O envelope tem o campo EventType para identificar o evento.
Você usa esse campo para encaminhar o JSON ao tratamento correspondente,
sem presumir que toda requisição contém uma mensagem textual.
Ocorrência
A sessão recebe mensagem ou muda de estado.
Seleção
eventsA assinatura escolhe os tipos entregues.
Receptor
O seu endpoint recebe o evento e responde HTTP 200.
Processamento
O fluxo trata a ocorrência e atualiza o histórico.
Os campos específicos ficam na raiz do payload conforme o evento.
A documentação apresenta objetos como message, chat e event.
Ela também esclarece que não existe um event_id universal para
todas as ocorrências. Você usa os identificadores previstos para o
tipo recebido, preservando as strings originais. Um receptor que exige
um único formato de envelope pode rejeitar eventos válidos de outro tipo.
Os filtros evitam respostas aos próprios envios
O campo excludeMessages declara quais mensagens ficam fora da entrega.
O valor wasSentByApi exclui mensagens classificadas como enviadas
pela API. Já fromMeYes exclui mensagens originadas pelo número
conectado. Esses filtros têm alcances diferentes: uma mensagem enviada
no celular pode vir do próprio número sem ter sido enviada pela API.
A escolha interfere no que o seu fluxo enxerga e no que deixa de receber.
Uma automação de resposta precisa reconhecer sua própria saída para não responder continuamente a ela. Você também pode precisar acompanhar as mensagens digitadas por um atendente no celular. Nesse caso, excluir tudo que vem do próprio número retira ocorrências que podem importar para o histórico. O filtro acompanha a finalidade da integração, enquanto o processamento mantém sua própria proteção contra ciclos de respostas e ações repetidas.
A resposta rápida separa recebimento e trabalho demorado
O receptor responde HTTP 200 imediatamente e encaminha
o processamento mais demorado para uma fila interna. Uma consulta externa,
a geração de uma resposta ou o download de um arquivo pode levar
mais tempo que a entrega do evento. Se tudo fica preso à mesma
requisição, o remetente pode interpretar a demora como falha mesmo
quando o seu fluxo continua trabalhando no conteúdo recebido.
Na orientação da UAZAPI, o receptor preserva o payload e responde sem
aguardar a gravação na fila nem consultas externas. A validação e o
processamento acontecem de forma assíncrona. Você acompanha falhas nessa
fila e reconcilia os registros pela API quando necessário, porque o HTTP
200 sozinho não comprova que o evento ficou armazenado. A documentação orienta tolerar eventos
duplicados e fora de ordem. Uma repetição da entrega não precisa
criar outra resposta no WhatsApp nem fazer uma mensagem já lida
voltar ao estado de apenas enviada.
O payload pode carregar uma credencial
O envelope documentado inclui campos como owner, BaseUrl,
instanceName e token. O token é sensível e não deve aparecer
em logs públicos. Você valida o vínculo entre a instância e a
integração autorizada no backend. O nome da instância ou o número
informado no payload, isoladamente, não substitui a autorização
que o seu sistema precisa aplicar antes de alterar uma conversa.
A uazapi mantém o serviço proprietário que envia esses eventos. O contrato público permite entender o formato da comunicação, mas não fornece uma licença aberta para o servidor. Na versão 2.6.9, a configuração pode acrescentar o tipo do evento ao caminho da URL. Essa opção exige que o receptor aceite os caminhos derivados. Um endpoint que atende apenas a URL original pode começar a responder com erro depois dessa alteração.
Os erros mostram onde a entrega parou
A consulta /webhook/errors apresenta falhas recentes da instância.
O campo stage diferencia problemas HTTP de falhas anteriores ao
envio. Quando o receptor responde com erro ou não responde,
o registro permite investigar o endereço e o tempo de atendimento.
Quando a fila interna está cheia, pode nem ter ocorrido uma tentativa
de chamada ao destino. Tratar essas duas situações como o mesmo
erro esconde a parte que você precisa conferir.
A página do n8n e do Chatwoot mostra a função desses eventos no atendimento. Para o receptor, o compromisso é preservar a ocorrência e aplicar o tratamento adequado. A confirmação HTTP descreve a entrega ao seu endpoint, enquanto a conclusão da automação e a resposta ao contato continuam sendo estados separados no histórico do seu sistema.