Pular para o conteúdo

Webhooks e assinatura

Como receber os eventos, verificar a assinatura X-Sales-Signature, testar o endpoint, e como funcionam as novas tentativas e o reenvio de entregas.

Ver em Markdown

A apiwpp envia cada evento com um POST ao webhookBaseUrl do projeto. A entrega é feita pelo menos uma vez: o mesmo evento pode chegar de novo, então aplique cada um de forma idempotente. Um projeto inativo não recebe webhooks.

1Configure o endpoint

O endpoint e a assinatura são do projeto e mudam com PATCH /tenants/{id}, com uma chave que tenha o escopo webhooks:write:

CampoO que é
webhookBaseUrlA URL que recebe os eventos. Precisa ser https, sem credenciais na URL, e o host tem de resolver só para endereços públicos. Redirecionamentos não são seguidos
webhookTokenUm valor seu, enviado em toda entrega no cabeçalho X-Webhook-Token
webhookSecretO segredo da assinatura HMAC. null ou "" desliga a assinatura
webhookHeadersCabeçalhos extras enviados em toda entrega (null remove todos). Nunca substituem os de assinatura
emitOutgoingtrue liga o evento message.outgoing

webhookToken, webhookSecret e os valores de webhookHeaders nunca são devolvidos: a resposta traz só hasWebhookSecret e webhookHeaderNames. Guarde o segredo no cofre do servidor que recebe os eventos antes de enviá-lo; se ele se perder, defina outro.

bashVer na referência
WEBHOOK_SECRET=$(openssl rand -hex 32)

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

Uma URL que não segue as regras é recusada com 400.

2Receba os eventos

Todo evento chega no mesmo envelope; data depende do type:

jsonmessage.delivery
{
  "type": "message.delivery",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-25T12:00:02.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "recipient": "5511988887777",
    "clientRef": "pedido-1234",
    "jid": "[email protected]",
    "phone": "+5511988887777"
  }
}
CampoDescrição
typeO tipo do evento
connectionIdA conexão (o número) que gerou o evento
tenantIdO projeto
externalIdO seu identificador da conexão, ou null
timestampQuando o evento aconteceu (ISO 8601)
dataOs campos do evento

Ignore os tipos de evento que você não conhece e os campos que não usa: o contrato só cresce (tipos e campos novos), nunca renomeia nem remove.

typeQuando
connection.statusA conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer (reason)
message.incomingAlguém escreveu para o número (texto, mídia, localização), numa conversa individual ou num grupo
message.outgoingO número enviou uma mensagem; só com emitOutgoing: true no projeto
message.deliveryUma mensagem enviada mudou de status: sent, delivered, read ou failed
message.send_failedUm envio com clientRef não vai acontecer
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
pingSó no teste do endpoint (passo 4)

Os campos de cada evento estão na página dele, em Webhooks.

Mídia recebida

Um message.incoming com mídia traz data.media.url, uma URL assinada e temporária do arquivo. Baixe-a sem credencial, exatamente como veio, até data.media.expiresAt (24 horas depois do recebimento, por padrão): veja Baixar mídia. Baixe o arquivo quando o evento chegar, em vez de guardar a URL, e trate a URL como um segredo: não a registre em log nem a repasse.

3Verifique a assinatura

Com um webhookSecret definido, cada tentativa de entrega traz estes cabeçalhos:

CabeçalhoConteúdo
X-Sales-TimestampSegundos unix do momento da tentativa (cada nova tentativa é assinada de novo)
X-Sales-Signaturesha256= + hex(HMAC-SHA256(webhookSecret, timestamp + "." + corpo bruto))
X-Webhook-TokenO webhookToken do projeto, enviado sempre, com ou sem assinatura
Content-Typeapplication/json

Para aceitar um evento:

  1. Leia o corpo bruto, os bytes exatamente como chegaram. Nunca assine de novo um objeto já convertido de JSON: a serialização muda e a assinatura não confere.
  2. Rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio: isso barra a repetição de entregas antigas.
  3. Calcule o HMAC-SHA256 de timestamp + "." + corpo com o segredo e compare com X-Sales-Signature em tempo constante.
  4. Responda 2xx logo e processe o evento fora da requisiçã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();

// express.raw: o corpo chega como Buffer, sem ser convertido de JSON
app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (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'));
  queue.add(event); // processe fora da requisição
  res.sendStatus(204);
});

Em Laravel, o corpo bruto é $request->getContent(), os cabeçalhos vêm de $request->header(...) e o segredo vem de config(...), nunca de getenv(): com php artisan config:cache, o arquivo .env deixa de ser lido e getenv() devolve false.

Sem webhookSecret, as entregas não são assinadas: confira pelo menos o X-Webhook-Token, também em tempo constante.

4Teste o endpoint

POST /tenants/webhook-test envia um evento ping à URL informada, com os mesmos cabeçalhos, a mesma assinatura, o mesmo limite de 10 segundos e as mesmas regras de URL das entregas reais. Nada é salvo, e o ping não entra no registro de entregas.

  • Com tenantId, o ping é assinado com o segredo guardado do projeto (a menos que você mande webhookSecret). O token e os cabeçalhos guardados só são usados quando webhookBaseUrl é a URL salva do projeto.
  • Para outra URL, mande webhookToken junto: sem ele, a resposta é 400.
bashVer na referência
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookBaseUrl": "https://crm.example.com/hooks/whatsapp", "tenantId": "'$TENANT_ID'"}'
200
{ "ok": true, "status": 200, "latencyMs": 184, "error": null }

status é o que o seu endpoint respondeu (null sem resposta), e error diz o que falhou, como "timeout" quando os 10 segundos acabaram. No ping, connectionId, tenantId e externalId vêm null, e data.message é "ping from WhatsApp Gateway admin".

5Respostas e novas tentativas

  • Responda 2xx em até 10 segundos; o corpo da resposta é ignorado. Faça o trabalho pesado depois, fora da requisição.
  • Qualquer outra resposta (3xx, 4xx, 5xx), um erro de rede ou o tempo esgotado conta como falha. Um redirecionamento é registrado como falha, sem ser seguido.
  • Uma entrega falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: 6 tentativas no total. Depois disso, ela fica no estado dead.
  • Depois de 5 falhas seguidas, a apiwpp pausa as entregas do projeto por 30 segundos, e a pausa dobra a cada teste que falha, até 5 minutos. Uma única entrega testa o endpoint antes de retomar; os eventos esperam na fila.
  • Um evento que passa 24 horas sem ser entregue fica dead.

6Registro e reenvio

GET /webhooks/deliveries (escopo logs:read) lista cada evento enviado, dos mais novos para os mais antigos, com o estado (delivered, retry ou dead), o status HTTP recebido, o erro, a latência, as tentativas, se foi assinado e o corpo enviado. Filtre com state e tenantId; limit vai até 200 (padrão 60). A resposta também traz counts por estado e stats com a taxa de sucesso e a latência média.

bashVer na referência
curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=50" \
  -H "Authorization: Bearer $API_KEY"

Quando o seu endpoint voltar (escopo webhooks:write):

  • POST /webhooks/deliveries/{id}/resend reenvia uma entrega dead ou retry, na hora e com novas tentativas. Uma entrega já feita responde 409, e uma cujo corpo não foi registrado também (corpos acima de 256 KB não são guardados).
  • POST /webhooks/deliveries/resend-dead reenvia todas as entregas dead dos seus projetos, até 1000 por chamada, das mais novas para as mais antigas, e responde { "requeued": 3 }. Com mais de 1000, chame de novo. As que não têm o corpo guardado continuam dead e voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: se requeued vier abaixo de 1000 e ainda houver entregas dead mais antigas, reenvie essas uma a uma com POST /webhooks/deliveries/{id}/resend.

Por padrão, o registro guarda as entregas por 7 dias. Para não perder eventos numa indisponibilidade longa, confira o estado dead depois de cada incidente e reenvie.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026