Ir para o conteúdo
Promovaweb

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
  1. O destino pertence ao seu sistema
  2. O tipo do evento define a interpretação
  3. Os filtros evitam respostas aos próprios envios
  4. A resposta rápida separa recebimento e trabalho demorado
  5. O payload pode carregar uma credencial
  6. Os erros mostram onde a entrega parou

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.

  1. Ocorrência

    A sessão recebe mensagem ou muda de estado.

  2. Seleção

    events

    A assinatura escolhe os tipos entregues.

  3. Receptor

    O seu endpoint recebe o evento e responde HTTP 200.

  4. Processamento

    O fluxo trata a ocorrência e atualiza o histórico.

Entrega de um evento selecionado até o processamento no sistema integrado.

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.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.