Configurando Webhooks no WhatsApp Business API

O que sao Webhooks?

Webhooks sao notificacoes HTTP enviadas automaticamente pela Meta sempre que um evento relevante acontece na sua conta do WhatsApp Business. Eles sao o mecanismo principal para receber mensagens de clientes, acompanhar status de entrega e gerenciar templates.

Tipos de Eventos

Os principais eventos que voce recebera via webhook sao:

• messages: Novas mensagens recebidas (texto, imagem, audio, documento, localizacao, etc.)
• statuses: Atualizacoes de status das mensagens enviadas (enviado, entregue, lido, falhou)
• message_template_status_update: Mudancas no status de aprovacao dos templates
• account_update: Alteracoes na conta (ban, restricao, phone number quality)

Configurando o Endpoint de Verificacao

O primeiro passo e criar um endpoint que responda ao desafio de verificacao da Meta. Quando voce registra um webhook, a Meta envia uma requisicao GET com um token de verificacao:

// Endpoint GET para verificacao
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

Processando Eventos

Apos a verificacao, as notificacoes chegam como requisicoes POST com um payload JSON. Responda sempre com 200 OK imediatamente e processe o evento de forma assincrona:

// Endpoint POST para receber eventos
app.post('/webhook', (req, res) => {
  // Responde imediatamente para evitar timeout
  res.sendStatus(200);

  const body = req.body;
  if (body.object === 'whatsapp_business_account') {
    body.entry?.forEach(entry => {
      entry.changes?.forEach(change => {
        if (change.field === 'messages') {
          processarMensagem(change.value);
        }
      });
    });
  }
});

Validacao de Assinatura

Para garantir que as requisicoes realmente vem da Meta, valide a assinatura HMAC-SHA256 presente no header X-Hub-Signature-256:

const crypto = require('crypto');

function validarAssinatura(payload, signature) {
  const expectedSig = crypto
    .createHmac('sha256', APP_SECRET)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expectedSig}`;
}

Seguranca: Nunca processe webhooks sem validar a assinatura. Atacantes podem enviar requisicoes falsas para seu endpoint.

Boas Praticas

• Responda com 200 em menos de 5 segundos — processe de forma assincrona
• Use uma fila de mensagens (Redis, RabbitMQ, SQS) para processamento resiliente
• Implemente idempotencia — webhooks podem ser entregues mais de uma vez
• Monitore a saude do endpoint com alertas de disponibilidade
• Registre logs detalhados para debugging

Conclusao

Webhooks bem configurados sao a espinha dorsal de qualquer integracao com o WhatsApp Business API. Invista em uma implementacao robusta, segura e resiliente para garantir que nenhuma mensagem se perca e que seus sistemas reajam em tempo real.