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.
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:
| Campo | O que é |
|---|---|
webhookBaseUrl | A 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 |
webhookToken | Um valor seu, enviado em toda entrega no cabeçalho X-Webhook-Token |
webhookSecret | O segredo da assinatura HMAC. null ou "" desliga a assinatura |
webhookHeaders | Cabeçalhos extras enviados em toda entrega (null remove todos). Nunca substituem os de assinatura |
emitOutgoing | true 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.
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:
{
"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"
}
}| Campo | Descrição |
|---|---|
type | O tipo do evento |
connectionId | A conexão (o número) que gerou o evento |
tenantId | O projeto |
externalId | O seu identificador da conexão, ou null |
timestamp | Quando o evento aconteceu (ISO 8601) |
data | Os 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.
type | Quando |
|---|---|
connection.status | A conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer (reason) |
message.incoming | Alguém escreveu para o número (texto, mídia, localização), numa conversa individual ou num grupo |
message.outgoing | O número enviou uma mensagem; só com emitOutgoing: true no projeto |
message.delivery | Uma mensagem enviada mudou de status: sent, delivered, read ou failed |
message.send_failed | Um envio com clientRef não vai acontecer |
message.reaction | Alguém reagiu a uma mensagem (ou removeu a reação) |
contact.resolved | Um remetente que chegou só com LID agora tem telefone |
group.joined, group.left, group.updated | O número entrou num grupo, saiu dele, ou o grupo mudou |
ping | Só 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çalho | Conteúdo |
|---|---|
X-Sales-Timestamp | Segundos unix do momento da tentativa (cada nova tentativa é assinada de novo) |
X-Sales-Signature | sha256= + hex(HMAC-SHA256(webhookSecret, timestamp + "." + corpo bruto)) |
X-Webhook-Token | O webhookToken do projeto, enviado sempre, com ou sem assinatura |
Content-Type | application/json |
Para aceitar um evento:
- 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.
- Rejeite um
X-Sales-Timestampa mais de 300 segundos do seu relógio: isso barra a repetição de entregas antigas. - Calcule o HMAC-SHA256 de
timestamp + "." + corpocom o segredo e compare comX-Sales-Signatureem tempo constante. - Responda
2xxlogo 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);
});<?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);import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request
SECRET = os.environ.get("WHATSAPP_WEBHOOK_SECRET", "")
# Sem segredo não há o que verificar: o servidor não sobe
if not SECRET:
raise RuntimeError("WHATSAPP_WEBHOOK_SECRET não está definido")
TOLERANCE_SECONDS = 300
app = Flask(__name__)
def is_signed(raw_body: bytes, timestamp: str, signature: str) -> bool:
if not timestamp.isdigit() or not signature:
return False
if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
return False
mac = hmac.new(SECRET.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(f"sha256={mac}", signature)
@app.post("/whatsapp/events")
def whatsapp_events():
raw_body = request.get_data() # os bytes como chegaram
if not is_signed(raw_body, request.headers.get("X-Sales-Timestamp", ""), request.headers.get("X-Sales-Signature", "")):
abort(401)
event = json.loads(raw_body)
queue.put(event) # processe fora da requisição
return "", 204Em 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ê mandewebhookSecret). O token e os cabeçalhos guardados só são usados quandowebhookBaseUrlé a URL salva do projeto. - Para outra URL, mande
webhookTokenjunto: sem ele, a resposta é400.
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'"}'{ "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
2xxem 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.
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}/resendreenvia uma entregadeadouretry, na hora e com novas tentativas. Uma entrega já feita responde409, e uma cujo corpo não foi registrado também (corpos acima de 256 KB não são guardados).POST /webhooks/deliveries/resend-deadreenvia todas as entregasdeaddos 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 continuamdeade voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: serequeuedvier abaixo de 1000 e ainda houver entregasdeadmais antigas, reenvie essas uma a uma comPOST /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
- Webhooks: o envelope e os campos de cada evento.
- Enviar mensagens: os envios que geram
message.deliveryemessage.send_failed. - LID e contact.resolved: remetentes que chegam sem telefone.
- Uso e registros: os registros de mensagens e de entregas.