O que são webhooks no WhatsApp

Resumo rápido

Webhook é um aviso automático: em vez de o sistema ficar perguntando "chegou mensagem?", a API oficial do WhatsApp avisa na hora em que algo acontece — uma mensagem do cliente ou o status de entrega de uma mensagem enviada. É o que permite a uma ferramenta com IA responder quase na hora. Quando você usa uma ferramenta como a Unred, essa parte técnica fica por conta dela.

• É a API da Meta avisando o sistema quando algo acontece
• Dois tipos principais: mensagem recebida e status de entrega
• Permite resposta quase imediata, sem ficar consultando o tempo todo
• O dono não configura nada: a ferramenta cuida do caminho oficial
• A URL e os campos exatos seguem a documentação vigente da Meta

Definição simples

Webhook é um termo técnico, mas a ideia é simples: é um aviso automático. Em vez de um sistema ficar perguntando 'chegou mensagem? e agora? e agora?', a API oficial do WhatsApp avisa o sistema na hora em que algo acontece. Esse aviso é o webhook.

É como a diferença entre ficar olhando a caixa de correio toda hora e ter alguém que toca a campainha quando chega carta.

O que um webhook costuma avisar

Na API oficial, os avisos cobrem os eventos importantes de uma conversa:

• Uma nova mensagem do cliente chegou
• Uma mensagem enviada foi entregue ou lida (status de entrega)
• Mudanças relevantes no estado da conversa

Exemplo: webhook de mensagem recebida

Quando um cliente manda uma mensagem, a API da Meta envia ao sistema um aviso com um formato de dados parecido com este (valores de exemplo, com aspas simples para facilitar a leitura):

{ 'object': 'whatsapp_business_account', 'entry': [ { 'id': 'ID_DA_CONTA', 'changes': [ { 'field': 'messages', 'value': { 'messaging_product': 'whatsapp', 'contacts': [ { 'profile': { 'name': 'Maria' }, 'wa_id': '5511999998888' } ], 'messages': [ { 'from': '5511999998888', 'id': 'wamid.ABC123', 'timestamp': '1751000000', 'type': 'text', 'text': { 'body': 'Oi, vocês atendem sábado?' } } ] } } ] } ] }

Em português claro, cada parte diz: 'from' é o número de quem enviou; 'id' é o identificador único da mensagem (útil para não processar a mesma duas vezes); 'timestamp' é a hora do envio; 'type' diz que é texto; e 'text.body' é o conteúdo que o cliente escreveu. É a partir daí que a IA entende o que o cliente quer e responde.

Exemplo: webhook de status (enviada, entregue, lida)

Além das mensagens recebidas, a API avisa o que aconteceu com o que a empresa enviou. Esse aviso de status tem um formato parecido com este:

{ 'object': 'whatsapp_business_account', 'entry': [ { 'changes': [ { 'field': 'messages', 'value': { 'messaging_product': 'whatsapp', 'statuses': [ { 'id': 'wamid.ABC123', 'status': 'delivered', 'timestamp': '1751000300', 'recipient_id': '5511999998888' } ] } } ] } ] }

Aqui, 'status' costuma passar por etapas como 'sent' (enviada), 'delivered' (entregue) e 'read' (lida). Isso é o que permite mostrar no CRM se a mensagem chegou e foi lida — o mesmo sinal dos "tiquinhos" do WhatsApp, só que disponível para o sistema. Os nomes e campos exatos seguem o que a Meta define na documentação atual.

Por que isso importa

Sem webhook, a automação seria lenta e ineficiente. É o webhook que permite a uma ferramenta com IA responder o cliente quase imediatamente: o aviso chega, a IA lê a mensagem e devolve a resposta. Para o dono do negócio, o detalhe técnico não importa muito — o que importa é o resultado: respostas rápidas e nenhuma mensagem perdida.

Boas práticas

Para quem cuida da parte técnica, alguns cuidados evitam dor de cabeça ao receber webhooks:

• Responder rápido ao webhook (confirmar o recebimento) e processar depois, em segundo plano
• Tratar avisos duplicados usando o 'id' da mensagem para não processar duas vezes
• Validar a origem do aviso antes de confiar no conteúdo
• Distinguir mensagem recebida (messages) de aviso de status (statuses)
• Registrar falhas para reprocessar sem perder eventos

Erros comuns

Alguns problemas aparecem com frequência em integrações de webhook:

• Demorar para responder ao aviso e fazer a plataforma reenviar em duplicidade
• Ignorar o 'id' e acabar respondendo o cliente duas vezes
• Confundir status de entrega com uma nova mensagem do cliente
• Assumir um formato fixo em vez de conferir a documentação vigente da Meta
• Não ter plano para reprocessar quando o sistema fica fora do ar por instantes

Checklist de implementação

Ao ligar o recebimento de webhooks pelo caminho oficial, vale conferir:

• O endpoint responde rápido e processa o conteúdo de forma assíncrona
• Há verificação da origem do aviso antes de agir sobre ele
• Mensagens duplicadas são descartadas pelo 'id'
• Mensagens recebidas e avisos de status são tratados separadamente
• Existe reprocessamento para eventos que falharem
• A URL e os tópicos exatos foram confirmados na documentação atual da Meta

Como a Unred usa webhooks

A Unred é um CRM com IA para WhatsApp que opera pelo caminho oficial e recebe esses avisos da API da Meta. Quando um cliente escreve, o webhook dispara, a IA entende a mensagem e responde, e a conversa entra organizada num funil. É parte do que faz o atendimento ser imediato — a base do No more red.