Skip to main content

Configurando Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos acontecem no WhatsApp (mensagens recebidas, status de entrega, etc.).

Como Funciona

  1. Um evento acontece (ex: mensagem recebida)
  2. A Wapizap API envia um POST para sua URL de webhook
  3. Sua aplicação processa o evento

Criar um Webhook


Eventos Disponíveis

Use ["*"] para receber todos os eventos (não recomendado em produção).

Recebendo Webhooks

Estrutura do Payload

Exemplo de Servidor (Node.js/Express)

Exemplo de Servidor (Python/Flask)


Validação de Assinatura

Para garantir que os webhooks vêm realmente da Wapizap, valide a assinatura:
  1. O header X-Webhook-Signature contém um HMAC-SHA256
  2. É calculado usando o secret que você definiu ao criar o webhook
  3. O payload é o corpo JSON da requisição
Sempre valide a assinatura em produção para evitar que terceiros enviem requisições falsas para seu endpoint.

Testar Webhook

Teste se seu endpoint está recebendo corretamente:

Atualizar Webhook


Listar Webhooks


Deletar Webhook


Melhores Práticas

Responda Rápido

Sempre responda com HTTP 200 em menos de 5 segundos. Processe dados de forma assíncrona.

Valide Assinaturas

Use o secret para validar que a requisição vem da Wapizap.

Use HTTPS

Sua URL de webhook deve usar HTTPS em produção.

Seja Idempotente

Webhooks podem ser reenviados. Use o messageId para detectar duplicatas.

Tratamento de Falhas

Se seu servidor não responder com 2xx:
  • 1ª tentativa: Imediata
  • 2ª tentativa: Após 1 minuto
  • 3ª tentativa: Após 5 minutos
  • 4ª tentativa: Após 30 minutos
  • Após 4 falhas, o webhook é marcado como inativo

Desenvolvimento Local

Para testar webhooks em desenvolvimento local, use um túnel:

ngrok

Cloudflare Tunnel


Debugging

Verificar Logs

No dashboard, você pode ver o histórico de webhooks enviados:
  • Status de entrega
  • Payload enviado
  • Resposta recebida
  • Tempo de resposta

Problemas Comuns


Próximos Passos

Enviar Mensagens

Responda mensagens recebidas via webhook

Tratamento de Erros

Lide com erros de forma elegante