Pular para o conteúdo
apiwpp

Webhooks do WhatsApp: como receber e validar mensagens no seu sistema

Configure o endereço do webhook, verifique a assinatura HMAC em Node.js e PHP e processe os eventos do WhatsApp sem duplicar nada.

Equipe apiwpp · 12 min de leitura

Enviar uma mensagem pela API é a parte fácil. O trabalho de verdade começa depois: o cliente respondeu, a mensagem foi lida, o número caiu, um envio não vai acontecer. Se o seu sistema precisa consultar a API de minuto em minuto para descobrir isso, ele chega atrasado e gasta requisições à toa.

Webhook resolve o problema pelo outro lado. Em vez de você perguntar, a apiwpp avisa: a cada evento do número, ela faz um POST para um endereço do seu sistema com um JSON descrevendo o que aconteceu. Se o termo é novo para você, o glossário explica o que é webhook em poucas linhas.

Este tutorial cobre o caminho completo: o formato dos eventos, como configurar o endereço e o segredo, como verificar a assinatura HMAC em Node.js e em PHP, como responder rápido e como processar cada evento uma única vez, mesmo quando ele chega duas vezes.

O envelope: todo evento chega no mesmo formato

Todos os eventos usam o mesmo envelope. Só o conteúdo de data muda conforme o type (aqui, uma mensagem recebida com parte dos campos):

{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-09-19T12:00:00.000Z",
  "data": {
    "jid": "[email protected]",
    "phone": "+5511988887777",
    "body": "Olá! Meu pedido já saiu?",
    "timestamp": 1789819200
  }
}

Cada campo tem um papel:

  • type diz o que aconteceu e decide como o seu código trata o evento.
  • connectionId identifica o número (a conexão) de onde o evento veio. Um projeto com vários números recebe todos no mesmo endereço, e é esse campo que separa um do outro.
  • tenantId é o projeto. externalId é o identificador que você mesmo deu ao projeto, útil para mapear o evento para um cliente do seu sistema sem consultar nada.
  • timestamp é o momento do evento, em ISO 8601.
  • data traz os detalhes. Nos eventos de mensagem, jid é o endereço interno do WhatsApp e phone é o telefone em E.164, quando é possível resolvê-lo.

Os tipos de evento

typeQuando chega
connection.statusA conexão abriu ou fechou, com o motivo em reason e se vai reconectar sozinha em willReconnect
message.incomingAlguém escreveu para o número: texto, mídia ou localização, em conversa individual ou em grupo
message.outgoingO número enviou uma mensagem, pela API ou digitada no celular. Opcional, ligado por projeto
message.deliveryUma mensagem enviada mudou de status: sent, delivered, read ou failed
message.send_failedUm envio feito com clientRef não vai acontecer, com o motivo
message.reactionAlguém reagiu a uma mensagem, ou removeu a reação
contact.resolvedUm remetente que chegou só com LID agora tem telefone
group.joined, group.left, group.updatedO número entrou num grupo, saiu dele, ou o grupo mudou

Dois detalhes evitam dor de cabeça. Primeiro, mídia recebida chega em data.media.url como um link assinado e temporário: baixe o arquivo quando o evento chegar, em vez de guardar o link, e não o registre em log. Segundo, um evento pode chegar com phone: null quando o remetente é identificado só por um LID; o evento contact.resolved avisa quando o telefone aparecer. O glossário de LID explica o porquê.

A lista completa, com o schema de cada evento, está na página de webhooks assinados e na documentação da API.

Configure o endereço e o segredo

Cada projeto tem um endereço de webhook, o webhookBaseUrl. Ele precisa ser uma URL https pública que responde direto: redirecionamentos não são seguidos. Todos os números do projeto enviam os eventos para esse mesmo endereço.

Em seguida, defina um segredo de assinatura. Com ele, cada entrega passa a trazer uma assinatura HMAC que prova que o evento veio da apiwpp e não foi alterado no caminho. Gere um valor aleatório e guarde no cofre de segredos do servidor que recebe os webhooks antes de enviá-lo, porque a API nunca o devolve:

WEBHOOK_SECRET=$(openssl rand -hex 32)

curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"webhookSecret\": \"$WEBHOOK_SECRET\"}"

A resposta traz "hasWebhookSecret": true, nunca o segredo. Se o valor se perder, defina um novo do mesmo jeito. A mesma rota altera o webhookBaseUrl e liga o evento message.outgoing com "emitOutgoing": true. A chave usada precisa do escopo webhooks:write.

Para testar na sua máquina, exponha a porta local com um túnel https (ngrok, cloudflared ou similar) e use essa URL como endereço do projeto enquanto desenvolve.

O caminho de um evento: POST assinado, resposta 2xx imediata e processamento em fila no seu sistema.

Verifique a assinatura HMAC

Com o segredo definido, cada tentativa de entrega traz três cabeçalhos:

CabeçalhoConteúdo
X-Sales-TimestampSegundos unix do momento da tentativa. Cada nova tentativa é assinada de novo
X-Sales-Signaturesha256= seguido do hex do HMAC-SHA256 de timestamp + "." + corpo bruto, com o segredo como chave
X-Webhook-TokenO token do projeto, enviado sempre, com ou sem assinatura

A verificação tem três regras, e todas importam:

  1. Use o corpo bruto. Calcule o HMAC sobre os bytes exatamente como chegaram. Se o seu framework já converteu o JSON em objeto, serializar de novo muda espaços e ordem, e a assinatura não confere.
  2. Recuse timestamps velhos. Um X-Sales-Timestamp a mais de 300 segundos do seu relógio é recusado. Isso impede que alguém capture uma entrega e a repita depois.
  3. Compare em tempo constante. Uma comparação comum de strings para no primeiro caractere diferente, e o tempo de resposta vaza informação. Use timingSafeEqual no Node.js e hash_equals no PHP.

Se o conceito de HMAC for novo, vale ler a definição antes de seguir.

Node.js com Express

A rota usa express.raw para receber o corpo como Buffer, sem conversão:

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
// Sem segredo não há o que verificar: o servidor não sobe
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')
const TOLERANCE_SECONDS = 300

function isSigned(rawBody, timestamp, signature) {
  if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false
  const mac = createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex')
  const expected = Buffer.from(`sha256=${mac}`)
  const received = Buffer.from(signature)
  return expected.length === received.length && timingSafeEqual(expected, received)
}

const app = express()

app.post('/whatsapp/events', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401)
  }
  const event = JSON.parse(req.body.toString('utf8'))
  await queue.add('whatsapp-event', { event, raw: req.body.toString('utf8') }) // processe fora da requisição
  res.sendStatus(204)
})

app.listen(3000)

O queue é a fila que você já usa (BullMQ, SQS, uma tabela no banco). O ponto é não fazer o trabalho pesado dentro da requisição. O mesmo padrão, com o envio de mensagens junto, está na página de integração com Node.js.

PHP puro

Em PHP, o corpo bruto vem de php://input:

<?php
$secret = getenv('WHATSAPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
    // Sem segredo não há o que verificar: recuse tudo até configurá-lo
    http_response_code(500);
    exit;
}

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_SALES_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SALES_SIGNATURE'] ?? '';

$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!$fresh || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// Enfileire $event e processe depois
http_response_code(204);

No Laravel, o corpo bruto é $request->getContent(), os cabeçalhos vêm de $request->header(...) e o segredo deve vir de config(...), nunca de getenv(): com php artisan config:cache, o .env deixa de ser lido e getenv() devolve false. Lembre também de tirar a rota do webhook da proteção CSRF. O passo a passo com middleware e Jobs está no tutorial de WhatsApp com PHP e Laravel.

O erro que mais se repete: segredo vazio

Um HMAC calculado com chave vazia pode ser reproduzido por qualquer pessoa. Se a variável de ambiente não chegou ao processo (deploy sem a variável, cache de configuração, typo no nome), o verificador precisa recusar tudo, como nos dois exemplos acima, e não comparar assinaturas com uma chave vazia.

Sem webhookSecret no projeto as entregas não são assinadas. Nesse caso, confira pelo menos o X-Webhook-Token, também em tempo constante. Mas prefira sempre o segredo.

Responda 2xx rápido e processe depois

A regra de ouro de qualquer webhook: responda 2xx em até 10 segundos e deixe o trabalho para depois. O corpo da sua resposta é ignorado. Qualquer outra coisa conta como falha: um 3xx, um 4xx, um 5xx, um erro de rede ou o tempo esgotado.

Na prática, a rota do webhook faz só três coisas: verifica a assinatura, grava o evento numa fila ou tabela e responde 204. Consultar o CRM, chamar outra API, gerar um PDF ou mandar uma resposta automática ficam para um worker.

Duas armadilhas comuns:

  • Tipos desconhecidos. Ignore os tipos de evento que você não trata e os campos que não usa, mas responda 2xx mesmo assim. O contrato só cresce: tipos e campos novos podem aparecer, e nada é renomeado ou removido. Um 400 para um tipo novo vira uma sequência de novas tentativas para nada.
  • Erro no processamento. Se o seu worker falhar, isso é problema da sua fila, não da entrega. Como o evento já foi aceito com 204, trate o erro com as novas tentativas da sua própria fila.

Processe cada evento uma única vez

A entrega é pelo menos uma vez (at-least-once). O mesmo evento pode chegar de novo: uma resposta que se perdeu na rede, um tempo esgotado do seu lado ou um reenvio feito por você no painel. O seu código precisa aceitar a repetição sem efeito duplicado, ou seja, ser idempotente.

O jeito mais simples é derivar uma chave de cada evento e guardá-la numa tabela com restrição de unicidade. Se a chave já existe, o evento já foi processado:

import { createHash } from 'node:crypto'

function eventKey(event, raw) {
  const d = event.data ?? {}
  switch (event.type) {
    case 'message.incoming':
      if (d.raw?.key?.id) return `in:${event.connectionId}:${d.raw.key.id}`
      break
    case 'message.outgoing':
      return `out:${event.connectionId}:${d.messageId}`
    case 'message.delivery':
      return `dlv:${event.connectionId}:${d.messageId}:${d.status}`
    case 'message.send_failed':
      return `fail:${event.connectionId}:${d.jobId}`
  }
  // Os demais tipos: o mesmo evento reenviado tem o mesmo corpo
  return `body:${createHash('sha256').update(raw).digest('hex')}`
}
CREATE TABLE whatsapp_events (
  event_key TEXT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- No worker: se nenhuma linha foi inserida, o evento já foi processado
INSERT INTO whatsapp_events (event_key) VALUES ($1) ON CONFLICT DO NOTHING;

Algumas observações sobre essa chave:

  • Em message.delivery, o mesmo messageId chega várias vezes, uma para cada status. Por isso o status entra na chave. Trate o status como uma progressão: uma mensagem já marcada como read no seu sistema não deve voltar para delivered.
  • Em message.incoming, o identificador da mensagem no WhatsApp está em data.raw.key.id. O campo raw segue o formato do WhatsApp, não o contrato da API: leia dele só o que os outros campos não trazem.
  • Para ligar os eventos aos seus registros, use o clientRef que você enviou no /send. Ele volta em message.outgoing, message.delivery e message.send_failed. Depois de 72 horas, um status tardio pode chegar com clientRef: null, e aí você correlaciona pelo messageId.

O outro lado da mesma moeda é o envio: repetir um POST /connections/{id}/send com o mesmo clientRef devolve o job original com "duplicate": true em vez de mandar a mensagem de novo. O guia sobre mensagens duplicadas junta as duas pontas.

Novas tentativas, registro e reenvio

Quando uma entrega falha, a apiwpp tenta de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: 6 tentativas no total. Depois disso, a entrega fica no estado dead. Se o seu endpoint falha em sequência, as entregas do projeto são pausadas por 30 segundos a 5 minutos e retomadas depois de uma entrega de teste; os eventos esperam na fila. Um evento que passa 24 horas sem ser entregue também fica dead.

Para saber o que aconteceu, cada entrega fica registrada com o estado (delivered, retry ou dead), o status HTTP que o seu servidor respondeu, o erro, a latência e o corpo enviado. O registro aparece no painel e na API:

curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead" \
  -H "Authorization: Bearer $APIWPP_KEY"

Quando o seu endpoint voltar, você reenvia o que ficou para trás:

  • POST /webhooks/deliveries/{id}/resend reenvia uma entrega, na hora e com novas tentativas;
  • POST /webhooks/deliveries/resend-dead reenvia todas as entregas dead dos seus projetos, até 1000 por chamada.

É aqui que a idempotência paga a conta: depois de um incidente, você reenvia tudo sem medo, e os eventos que já tinham sido processados são descartados pela chave. Os registros ficam guardados por alguns dias (7 por padrão), então confira as entregas dead logo depois de cada incidente.

Registro de entregas no painel: estado, status HTTP e latência de cada evento, com o botão de reenvio.

Um roteador de eventos que aguenta o tempo

Com a entrega segura e sem duplicidade, o que sobra é a regra de negócio. Um roteador simples no worker resolve a maioria dos casos:

async function handle(event) {
  switch (event.type) {
    case 'message.incoming':
      return tickets.addMessage(event.externalId, event.data)
    case 'message.delivery':
      return messages.updateStatus(event.data.clientRef ?? event.data.messageId, event.data.status)
    case 'message.send_failed':
      return messages.markFailed(event.data.clientRef, event.data.reason)
    case 'connection.status':
      if (event.data.status === 'close' && event.data.willReconnect === false) {
        return alerts.notify(`Número ${event.connectionId} desconectado: ${event.data.reason}`)
      }
      return
    default:
      return // tipo que você não trata: ignore
  }
}

Repare no connection.status: avise alguém na hora quando o fechamento vem com willReconnect: false (por exemplo, logged_out, que exige um QR code novo). Com willReconnect: true, a apiwpp reconecta sozinha; só avise se o open não chegar dentro do prazo que você definir. Esse evento também informa o motivo reachout_timelock, um bloqueio temporário de novas conversas, assunto do guia sobre como evitar o bloqueio do número.

Se você usa ferramentas de automação, o mesmo envelope funciona num nó Webhook do n8n. E se o seu produto é um SaaS em que cada cliente conecta o próprio número, o externalId é o que liga cada evento ao cliente certo, como mostra o guia de WhatsApp dentro do seu SaaS.

Como começar hoje

  1. Crie uma rota https pública no seu sistema que leia o corpo bruto e responda 204.
  2. Gere o segredo com openssl rand -hex 32, guarde no cofre do servidor e defina no projeto com PATCH /tenants/{id}.
  3. Implemente a verificação da assinatura com tolerância de 300 segundos e comparação em tempo constante, recusando tudo se o segredo estiver vazio.
  4. Grave cada evento numa fila e processe num worker, com uma chave de idempotência e uma tabela com restrição de unicidade.
  5. Ignore tipos de evento desconhecidos, sempre respondendo 2xx.
  6. Crie sua conta na apiwpp, conecte um número e mande uma mensagem para ele: o primeiro message.incoming chega no seu endereço em seguida. Os planos por número estão em preços.

Perguntas frequentes

Por que o mesmo evento chegou duas vezes no meu webhook?

Porque a entrega é pelo menos uma vez: se a resposta do seu servidor se perde, demora mais de 10 segundos ou não é 2xx, a apiwpp tenta de novo. Reenvios feitos no painel também repetem eventos. Por isso cada evento deve ser processado de forma idempotente, com uma chave como o messageId somado ao tipo e ao status.

A assinatura não confere. O que pode estar errado?

Quase sempre é o corpo: o HMAC precisa ser calculado sobre os bytes exatamente como chegaram, antes de qualquer conversão de JSON. Confira também se a mensagem assinada é o timestamp, um ponto e o corpo, se o segredo é o mesmo definido no projeto e se o relógio do servidor está certo, já que timestamps a mais de 300 segundos são recusados.

Quanto tempo tenho para responder a um webhook?

Até 10 segundos, e a resposta precisa ser 2xx. O corpo da resposta é ignorado. Grave o evento numa fila, responda na hora e faça o processamento pesado num worker.

O que acontece se o meu servidor ficar fora do ar?

Cada entrega é tentada 6 vezes, com intervalos de cerca de 2 a 32 segundos, e as entregas do projeto são pausadas por alguns minutos se o endpoint falha em sequência. O que não for entregue fica no estado dead. Quando o servidor voltar, reenvie uma entrega ou todas as dead pelo painel ou pela API.

Posso receber as mensagens que eu mesmo envio?

Sim, com o evento message.outgoing, que é opcional e ligado por projeto com emitOutgoing: true. Ele informa a origem de cada mensagem: API, para o que saiu pela integração, ou PHONE, para o que foi digitado no celular. É útil para espelhar no seu sistema a conversa completa.

Preciso de um endereço de webhook para cada número?

Não. O endereço é do projeto, e todos os números do projeto enviam os eventos para ele. O campo connectionId diz de qual número veio cada evento. Se você atende vários clientes, use um projeto por cliente, cada um com o próprio endereço e segredo.


Leia também:

Conecte seu primeiro número hoje.

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