FAQ Webhook
As perguntas que mais aparecem na primeira integração por webhook, com a causa de cada uma. Se algo não está chegando, comece por aqui antes de procurar defeito no seu código.
Dúvidas Comuns
Configurei o endereço e não chega nada. Confira três coisas, nessa ordem: o seu receptor aceita POST com corpo em JSON; o endereço está completo e acessível de fora da sua rede; e o evento realmente aconteceu no lugar certo — um webhook de Setor só dispara para atendimentos daquele Setor.
Estou recebendo cada evento duas vezes. É quase sempre o webhook da Conexão e o do Setor ligados ao mesmo tempo. Quando o atendimento está no Setor configurado, os dois disparam. Se só o Setor interessa, deixe o campo da Conexão vazio.
Recebi o aviso mas o campo mensagem veio vazio. O cliente mandou um arquivo. Arquivo gera dois avisos seguidos: o primeiro chega no formato de mensagem, com o campo trazendo só uma indicação do tipo (Áudio, o nome do arquivo quando é PDF, ou vazio quando é imagem ou vídeo). O segundo, com acao igual a fila-data, é o que traz a mídia.
Como sei se a mensagem foi enviada ou recebida? Pelo campo fromMe: false é do cliente para você, true é de você para o cliente. Não use o campo name para isso — ele traz o nome do cliente quando a mensagem é recebida e o celular dele quando é enviada, e essa troca é o que mais confunde quem está começando.
Meu código lê acao e o aviso de tag não é reconhecido. No aviso de tag da Conexão e do Setor a chave se chama action, não acao. Trate os dois nomes.
O que são webhookUrl e executionMode no fim dos exemplos? Não são da plataforma: é o envelope que a ferramenta de automação acrescenta ao registrar a chamada que recebeu. O que a plataforma envia é o conteúdo de body.
Como descubro se veio texto, áudio ou figurinha? Pelo nome da chave dentro de body.msg.message. Texto do celular vem como conversation e texto do WhatsApp Web como extendedTextMessage; os demais são audioMessage, imageMessage, videoMessage, documentMessage, reactionMessage, stickerMessage, contactMessage e locationMessage.
O aviso é reenviado se o meu sistema estiver fora do ar na hora? Não conte com isso. Trate cada aviso como entrega única: receba, registre o quanto antes e só depois processe. Para o que não pode faltar, guarde o que chegou e confira o restante por API.
O payload traz dados sensíveis? Traz. Os avisos de Conexão e de Setor carregam o token da Conexão (em token_origin, connection_token e ticketData.whatsapp.token), além do nome e do telefone do contato. Aponte apenas para endereços seus, sob HTTPS, e não registre o corpo inteiro em log que terceiros possam ler.
Qual webhook eu uso para quê? O da Conexão para espelhar tudo que passa por um canal. O de Setor quando só um time interessa. O de Eventos para o que não é mensagem de cliente — nota interna, tag, status de usuário e CRM. E o Trigger quando o sentido é o contrário: um sistema de fora avisando a plataforma para iniciar um fluxo.
O Webhook Trigger não inicia o fluxo. Três campos são obrigatórios no envio do sistema externo: nome, celular e email. Faltando um, não há para quem enviar nem com que nome tratar. Confira também se o Setor selecionado no Trigger é o que tem o fluxo vinculado.
Cliquei em Atualizar Dados no Trigger e não apareceu payload nenhum. O botão mostra a última requisição recebida — ele não cria uma. Faça o sistema externo disparar de verdade e clique depois.
As variáveis do Trigger não são substituídas no fluxo. Elas se escrevem entre sinais de porcentagem: %nome%, %celular%, %email%, %extra1%. E só existem depois de apontadas para os campos do payload, no passo de definir as variáveis.
Preciso de webhook ou de API? Se o seu sistema estaria perguntando de tempos em tempos "aconteceu algo novo?", é webhook. Se ele precisa de um dado no momento em que quiser, é API. Na maioria das integrações os dois convivem: o webhook avisa, e a API completa o que o aviso não trouxe.