Webhook do WhatsApp: a peça que quebra em silêncio e derruba a operação inteira

O que chega pelo webhook

Não é só mensagem. O webhook entrega vários tipos de evento, e cada um serve para uma coisa diferente na operação:

• Mensagens recebidas — texto, áudio, imagem, vídeo, documento, localização, contato e resposta a botão ou lista.
• Status de mensagem enviada — enviado, entregue, lido e falha, com o motivo da falha quando existe.
• Eventos de template — aprovação, rejeição e mudança de status de um modelo de mensagem.
• Qualidade e limite do número — quando a classificação de qualidade muda ou o tier de envio sobe ou desce.
• Eventos da conta — alterações na conta comercial, no número e em permissões.

Os três primeiros são os que a operação sente todo dia. Os dois últimos são os que evitam surpresa: empresa que não escuta evento de qualidade só descobre que o número piorou quando o disparo para.

Os campos que precisam estar ligados

Este é o erro silencioso mais comum de toda a API oficial. A assinatura do webhook tem campos individuais que precisam ser marcados um a um, e um campo desligado não gera erro em lugar nenhum: simplesmente aquele tipo de evento nunca chega.

O resultado típico: a empresa configura o webhook, testa o envio, funciona, e descobre dias depois que as respostas dos clientes nunca apareceram — porque o campo de mensagens não estava marcado. Ou o contrário: as mensagens chegam, mas ninguém sabe se foram lidas, porque o campo de status ficou de fora.

A checagem que resolve é simples e precisa ser feita depois de qualquer mexida na configuração: entrar na assinatura do webhook, conferir que os campos de mensagem e de status estão marcados, e mandar uma mensagem de teste de um celular pessoal para o número da empresa, verificando se ela aparece no sistema em segundos.

A assinatura fica em dois lugares diferentes

Outro ponto que derruba integrações: a configuração de webhook não vive em um lugar só. Existe a configuração no nível do aplicativo, onde ficam a URL de callback e o token de verificação, e existe a assinatura por conta comercial, que determina de quais contas aquele aplicativo recebe eventos.

Uma configuração sem a outra produz exatamente o sintoma mais frustrante possível: nada chega e nenhum erro aparece. A URL está certa, o token está certo, os campos estão marcados — e o silêncio continua, porque aquela conta comercial específica nunca foi assinada.

Quando um número novo é conectado, ou quando a empresa passa a usar uma conta comercial diferente, essa assinatura precisa ser refeita. É a causa número um de "funcionava e parou" depois de reconectar um número.

O que o endereço do webhook precisa ter

• Ser público e acessível pela internet, com certificado válido. Endereço interno ou com certificado vencido é recusado.
• Responder rápido. A Meta espera uma confirmação em poucos segundos. Servidor que processa tudo antes de responder acaba recebendo reenvio e mensagem duplicada.
• Validar a assinatura de segurança enviada em cada requisição, para garantir que o evento veio mesmo da Meta e não de alguém que descobriu a sua URL.
• Aguentar rajada. Um disparo grande gera muitos eventos de status em pouco tempo.
• Ser estável. Falha repetida pode levar a Meta a suspender o envio de eventos para aquele endereço.

O detalhe da resposta rápida é o que mais causa duplicação de mensagem em integrações caseiras: o correto é confirmar o recebimento imediatamente e processar depois, em segundo plano.

O webhook fica preso ao endereço do servidor

Este ponto merece destaque porque quebra operações inteiras de forma silenciosa: se você trocar de servidor, de provedor de hospedagem ou de endereço público, o webhook aponta para um lugar que não existe mais — e as mensagens simplesmente param de chegar, sem nenhum aviso, sem nenhum erro visível no painel.

O envio continua funcionando normalmente, o que torna o diagnóstico mais difícil: a equipe consegue mandar mensagem, os clientes recebem, e ninguém entende por que as respostas sumiram. É uma das falhas que mais demoram a ser identificadas.

A providência é incluir a reconfiguração do webhook no procedimento de qualquer mudança de infraestrutura, e fazer o teste de ponta a ponta logo depois — mandar uma mensagem de fora e confirmar que ela apareceu.

Status de entrega: o que cada um significa

Os eventos de status são o que permitem medir a operação, e cada um carrega uma informação diferente:

• Enviado — a Meta aceitou a mensagem. Não significa que chegou.
• Entregue — chegou ao aparelho do destinatário.
• Lido — o destinatário abriu a conversa, quando a confirmação de leitura está ativa do lado dele.
• Falha — não foi entregue, com um código e uma descrição do motivo.

A diferença entre enviado e entregue é a métrica mais reveladora de um disparo. Uma lista com muitos envios aceitos e poucas entregas indica base ruim, números inexistentes ou bloqueio — e insistir nela é o caminho mais rápido para derrubar a qualidade do número.

Webhook e a janela de 24 horas

Existe uma ligação direta entre o webhook e a regra comercial mais importante da API oficial: a janela de atendimento. Quando um cliente envia uma mensagem, abre-se um período em que a empresa pode responder livremente, com mensagem escrita na hora, sem template e sem o custo de iniciar uma conversa. Passado esse período, só é possível retomar com um modelo aprovado.

O evento que marca o início dessa janela é justamente o que chega pelo webhook. Isso significa que uma configuração ruim não causa apenas atraso: ela pode fazer a empresa perder a janela inteira. Se a mensagem do cliente demora horas para aparecer no sistema, ou não aparece, o vendedor responde tarde ou responde fora do prazo — e aí precisa de template, com custo e com a frieza de uma mensagem padronizada.

Na prática, esse é o argumento econômico mais concreto para levar o webhook a sério. Cada resposta perdida por evento que não chegou é, ao mesmo tempo, um lead esfriando e um custo adicional para retomar a conversa. Em operações com volume, a diferença entre um webhook saudável e um webhook instável aparece direto no custo mensal de conversas iniciadas pela empresa.

Os sintomas e o que cada um significa

• Envio funciona, recepção não — campos de mensagem desligados ou conta comercial não assinada.
• Funcionava e parou depois de reconectar o número — assinatura da conta comercial precisa ser refeita.
• Mensagens chegam duplicadas — servidor demorando a confirmar o recebimento, o que provoca reenvio.
• Mensagens somem em horário de pico — servidor não suporta a rajada de eventos.
• Parou tudo depois de trocar de servidor — URL antiga no webhook.
• Status nunca atualiza — campo de status não assinado.

Por que quase ninguém deveria fazer isso sozinho

Tecnicamente, qualquer empresa pode receber o webhook em um servidor próprio. Na prática, isso significa manter um serviço disponível vinte e quatro horas por dia, tratar rajada, validar assinatura, evitar duplicidade, guardar histórico, lidar com reconexão de número e refazer configuração toda vez que algo muda na infraestrutura.

É trabalho contínuo de infraestrutura, não um projeto que termina. E o custo de errar é alto de um jeito específico: o erro não aparece como falha, aparece como silêncio — cliente que respondeu e ninguém viu.

Por isso a maioria das empresas usa um sistema que já cuida disso e entrega a parte que interessa: a conversa aparecendo na tela do vendedor, o histórico guardado, o status de cada mensagem visível e um relatório que mostra entrega, leitura e resposta sem ninguém precisar olhar log.

O webhook não guarda histórico — e isso importa

Uma confusão comum faz empresas acreditarem que, por estarem na API oficial, suas conversas estão guardadas em algum lugar da Meta, prontas para serem consultadas depois. Não estão. A API oficial entrega eventos em tempo real e não funciona como um arquivo de conversas: o que não for armazenado por quem recebe simplesmente não existe depois.

As consequências disso aparecem em três momentos muito concretos. No primeiro, quando um cliente antigo volta e ninguém consegue ver o que foi combinado seis meses atrás. No segundo, quando um vendedor sai da empresa e a conversa dele precisa ser assumida por outra pessoa. No terceiro, quando surge uma discussão sobre o que foi ou não prometido, e a empresa não tem registro.

É por isso que a pergunta sobre onde fica o histórico deveria vir antes da pergunta sobre preço na escolha de qualquer provedor. Um sistema que guarda todas as conversas, permite busca por cliente e exporta os dados quando você pedir transforma o webhook em memória da empresa. Sem isso, cada mensagem recebida é um evento que passa — visto por uma pessoa, em um momento, e depois perdido.

Como testar se está tudo funcionando

Um roteiro de cinco minutos que deveria ser refeito depois de qualquer alteração:

• mande uma mensagem de um celular pessoal para o número da empresa e confirme que ela aparece no sistema em segundos;
• responda pelo sistema e confirme que o status muda de enviado para entregue e depois para lido;
• mande uma imagem e um áudio, porque tipos de mídia às vezes falham separadamente;
• teste um botão ou uma lista interativa, se você usa esse recurso;
• confira se um template enviado registra o status corretamente.

Fazer esse teste sempre que um número for conectado, reconectado ou migrado evita a descoberta tardia de que a operação passou dias sem receber nada.

Por onde começar

Se você já opera: faça o teste de ponta a ponta hoje, confira se os campos de mensagem e status estão assinados, verifique se a conta comercial está na lista de assinaturas do aplicativo e registre em algum lugar que mudança de servidor exige reconfigurar o webhook. Se você está montando agora: escolha um sistema que assuma essa camada, e use o tempo que sobra para cuidar do que realmente gera receita — velocidade de resposta, distribuição de lead e acompanhamento. Webhook bem configurado é invisível; mal configurado, é silêncio — e silêncio, nesse canal, é venda perdida sem ninguém perceber.