Pular para o conteúdo
apiwpp
Termo

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.