Pular para o conteúdo principal

Webhooks explicado para leigo

Resumo: Webhook é uma "campainha" entre dois sistemas. O gateway aperta a campainha (faz uma chamada HTTP) na sua URL toda vez que algo acontece — mensagem chegou, foi entregue, lida, etc. Seu sistema escuta e processa.

Quando usar isso​

Quando alguém te falou "configure o webhook" e você não sabe o que isso significa. Ou quando o suporte pediu para conferir se o webhook está "funcionando". Esta página explica em linguagem comum.

Analogia simples​

Imagine que você assinou uma revista mensal. Tem duas formas de receber:

  1. Pull (puxar): você vai até a banca todo mês perguntar se chegou a edição nova.
  2. Push (empurrar): a editora entrega na sua casa quando publica.

Webhook é o método "push" entre sistemas. O gateway entrega na sua URL automaticamente, em vez de você ficar perguntando "tem mensagem nova? tem mensagem nova?".

Como configurar​

Na hora de criar um canal (ou editar um existente), você informa três coisas:

CampoO que é
URLO endereço web público do seu sistema (ex.: https://meusistema.com/webhooks/whatsapp)
Secret (segredo)Uma senha aleatória (mínimo 16 caracteres) que vai junto em cada chamada — sua aplicação confere para ter certeza de que o request veio mesmo do gateway
Events (opcional)Lista de eventos que você quer receber (ex.: só message:received). Vazio = recebe tudo.

Um exemplo prático​

Suposição: você é dono de uma clínica e tem um sistema próprio rodando em https://clinica.com.br. Você criou um endpoint (uma "porta de entrada") em https://clinica.com.br/api/whatsapp para receber notificações.

Quando um paciente manda uma mensagem para o WhatsApp da clínica:

  1. O gateway recebe a mensagem do paciente.
  2. Faz uma chamada HTTP POST para https://clinica.com.br/api/whatsapp com um JSON parecido com:
{
  "type": "message:received",
  "channelId": "abc123-...",
  "from": "+5511999999999",
  "message": {
    "id": "wamid.xxxx",
    "text": "Olá, gostaria de marcar consulta",
    "timestamp": "2026-05-21T14:35:00Z"
  }
}
  1. Seu sistema lê esse JSON e faz o que precisa: salva a mensagem no banco, abre um ticket, manda alerta pro atendente, etc.

Sobre o "Secret" (segredo)​

Como qualquer URL pública pode receber chamadas de qualquer pessoa, o secret serve para você confirmar que a chamada veio mesmo do gateway (e não de alguém tentando enganar seu sistema).

Para cada chamada, o gateway inclui um cabeçalho HTTP chamado assinatura (HMAC) calculada com o seu secret. Seu sistema recalcula a mesma assinatura e compara — se bater, é legítimo.

⚠️ Atenção: Nunca compartilhe o secret em código público (GitHub, etc.). Trate como uma senha. Se vazar, regenere no painel.

Retry automático​

Se o seu sistema estiver fora do ar ou retornar erro quando o gateway tentar entregar:

  • O gateway tenta de novo algumas vezes, com intervalos crescentes (a primeira em segundos, depois minutos, depois horas).
  • Após várias tentativas falhas, o evento vai para uma "DLQ" (Dead Letter Queue) — uma fila de eventos que não conseguiram ser entregues.
  • Você pode reprocessar manualmente os eventos da DLQ pelo painel, em Webhooks → Falhas.

Para que tipo de URL meu webhook deve apontar?​

  • Precisa ser pública (acessível pela internet — não localhost).
  • Precisa aceitar HTTPS (não HTTP simples — a Meta exige criptografia).
  • Precisa responder em até 20 segundos com status 2xx (200, 201, etc.). Se demorar mais ou der erro, conta como falha.
  • Idealmente, deve responder rápido (em até 1-2 segundos) e processar o evento em background.

Dúvidas comuns​

Quem cria o endpoint do meu lado? Geralmente é o seu time de desenvolvimento (ou o seu fornecedor de software). É um endpoint HTTP comum, como qualquer formulário web.

Tem como ver os webhooks falhando? Sim. No painel, em Webhooks → Entregas, você vê cada chamada feita, o status (sucesso/falha), o tempo de resposta e o conteúdo enviado/recebido. Útil para depurar.

Posso ter múltiplos webhooks por canal? Sim, há o conceito de "Shared Webhook" — uma configuração de webhook compartilhada entre vários canais. Útil quando você tem 10 números da mesma empresa e quer enviar todos para a mesma URL.

O webhook é em tempo real? Sim, a latência típica é de 2 a 5 segundos entre o cliente mandar a mensagem e seu sistema receber o webhook.

E se eu não quiser webhook? Você pode usar o endpoint GET /v1/events para "puxar" eventos manualmente, ou conectar via streaming SSE. Mas o método recomendado é webhook.

Artigos relacionados​