O que é webhook
Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.
Atualizado em
Um webhook inverte a direção da integração. Numa chamada de API comum, o seu sistema pergunta e o serviço responde. Com um webhook, é o serviço que avisa o seu sistema: ele faz um POST para um endereço que você cadastrou sempre que acontece algo que interessa, como uma mensagem recebida, uma confirmação de leitura ou um número que desconectou.
A alternativa ao webhook é o polling: consultar a API a cada poucos segundos para descobrir se há novidades. Ele gasta requisições à toa, atrasa a informação e esbarra em limites de uso. O webhook entrega o evento uma vez, no momento em que ele acontece.
Como funciona no WhatsApp
Numa API de WhatsApp, o webhook é o único jeito prático de receber mensagens. Na apiwpp, cada projeto tem um endereço de webhook, uma URL https pública que responde direto, sem redirecionamentos. Todos os números do projeto enviam os eventos para ele, sempre no mesmo envelope. Quando um cliente escreve para o número, chega um message.incoming como este:
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "loja-42",
"timestamp": "2026-09-25T12:00:02.000Z",
"data": {
"jid": "[email protected]",
"phone": "+5511988887777",
"body": "Olá! Tem horário amanhã às 10h?",
"timestamp": 1790337602,
"raw": { "key": { "id": "3EB0C767D26A1D8A3F52", "fromMe": false } }
}
}
O campo type diz o que aconteceu e data traz os detalhes daquele tipo de evento. O connectionId identifica o número que recebeu a mensagem, e o externalId é o identificador do seu sistema que você associou à conexão, como o id do cliente.
Além de mensagens recebidas, a apiwpp avisa por webhook as mudanças de status das mensagens enviadas (message.delivery), os envios que não vão acontecer (message.send_failed), as reações, a conexão que abriu ou fechou (connection.status) e as mudanças nos grupos de que o número participa. A lista completa está em webhooks assinados.
O que o seu endpoint precisa fazer
Um endpoint de webhook bem feito segue quatro regras:
- Conferir a assinatura. O endereço é público, e qualquer pessoa que o descubra pode enviar dados falsos para ele. A apiwpp assina cada entrega com HMAC-SHA256 sobre o corpo e um timestamp, e o seu código confere antes de aceitar o evento.
- Responder rápido. Devolva um status
2xxem até 10 segundos e deixe o trabalho pesado para depois, numa fila do seu sistema. - Ignorar o que não conhece. Tipos de evento e campos novos podem aparecer com o tempo. Descarte os que você não usa em vez de devolver erro.
- Ser idempotente. A entrega é feita pelo menos uma vez, então o mesmo evento pode chegar de novo.
Entregas repetidas e idempotência
Se o seu servidor processou o evento mas a resposta se perdeu, demorou demais ou não foi 2xx, a apiwpp tenta de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: 6 tentativas no total. Reenvios feitos pela API também repetem eventos.
Por isso o seu código deve ser idempotente: guardar o identificador de cada evento já processado e ignorar os repetidos. No message.incoming, o identificador da mensagem está em data.raw.key.id; nos eventos de envio, como message.delivery, está em data.messageId, somado ao status. O tutorial webhooks do WhatsApp mostra esse controle com código completo.
Perguntas frequentes
Qual é a diferença entre webhook e API?
A API é o caminho do seu sistema até o serviço: você chama quando quer enviar ou consultar algo. O webhook é o caminho de volta: o serviço chama o seu sistema quando algo acontece. Uma integração com WhatsApp usa os dois.
O meu servidor precisa estar sempre no ar?
É o ideal, mas uma queda curta não perde eventos. A apiwpp tenta de novo cada entrega que falha, guarda o registro de cada uma e permite reenviar pela API as entregas que não chegaram.
Posso testar um webhook na minha máquina?
Pode, desde que o endereço seja uma URL https pública. Na máquina local, use uma ferramenta de túnel que exponha o seu servidor com https e cadastre esse endereço no projeto durante os testes.
Posso ter um webhook para cada número?
O webhook é configurado por projeto, e todos os números do projeto usam o mesmo endereço, diferenciados pelo connectionId. Se você precisa de endereços separados, por exemplo um por cliente, crie um projeto para cada um.
Outros termos
Todos: Glossário →HMAC é um código calculado a partir de uma mensagem e de um segredo compartilhado, com uma função de hash como SHA-256. Quem tem o segredo recalcula o código e confirma que a mensagem veio de quem diz e não foi alterada no caminho.
Uma operação é idempotente quando repeti-la tem o mesmo efeito que fazê-la uma vez. Em APIs, isso se consegue com uma chave de idempotência: o cliente manda o mesmo identificador em cada tentativa e o servidor reconhece a repetição em vez de executar de novo.
API não oficial do WhatsApp é um serviço que conecta um número comum pelo protocolo do WhatsApp Web, como um aparelho conectado, e expõe envio e recebimento de mensagens por HTTP. Não passa pela Meta: não exige aprovação, mas o número pode ser restringido.