Como chegam ao seu servidor as mensagens do WhatsApp: direto ou gerido, e verificar a assinatura
Cada número ligado através do easyCoexistence tem um modo de entrada. Direto para o seu sistema (direto): a Meta envia os webhooks para o seu endpoint HTTPS, um segredo no URL serve de credencial, e as automatizações ficam desligadas. Através do easyCoexistence (gerido): a Meta entrega ao easyCoexistence, as automatizações podem responder, e um Forward URL opcional recebe o valor original enviado pela Meta, com os dados da ligação, assinado com X-EC-Signature para verificar.
Tentativas por entrega reencaminhada, espaçadas 1 min, 5 min, 30 min, 2 h, 6 h e 24 h, cerca de 33 horas no total.
Tempo que cada tentativa de reenvio espera por um 2xx antes de ser considerada falhada.
Limite sugerido para a idade do t da assinatura; os reenvios são assinados de novo, pelo que as entregas genuínas ficam dentro dele.
Tempo durante o qual a Meta repete um webhook direto que recebeu algo diferente de HTTP 200, o que pode repetir mensagens.
Maior payload de webhook enviado pela Meta, incluindo os blocos de histórico.
Registos de execução guardados para um número gerido, com o texto das mensagens e das respostas; o próprio texto das mensagens é guardado 30, 90 ou 365 dias, à sua escolha.
Qual é a diferença entre direto e gerido?
Onde a Meta entrega os webhooks de mensagens do número. Gerido, apresentado como Através do easyCoexistence, significa que a Meta entrega ao easyCoexistence, que verifica a assinatura da Meta, executa as suas automatizações, guarda as conversas para Conversas e, se definir um Forward URL, lhe transmite cada alteração da Meta, assinada com um segredo que só a sua organização detém. Direto, apresentado como Direto para o seu sistema, significa que o easyCoexistence define o seu endpoint HTTPS como destino de webhook substituto na WhatsApp Business Account do número, para que a Meta envie diretamente para si e as mensagens nunca passem pelo easyCoexistence.
Os webhooks operacionais por trás da monitorização, como account_update e as alterações de qualidade, continuam no easyCoexistence em ambos os modos, razão pela qual os alertas continuam a funcionar em qualquer dos casos.
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
Como se muda um número de um modo para o outro?
Na página do número, o cartão Para onde vão as mensagens recebidas mostra o modo como duas opções, Através do easyCoexistence e Direto para o seu sistema. Guardar um destino de webhook, no cartão Encaminhar mensagens recebidas para o seu webhook ou com set_webhook_destination, torna o número direto. Escolher Através do easyCoexistence remove de imediato esse destino na Meta, por isso adicione o mesmo URL como Forward URL para continuar a receber. Os reenvios em fila são descartados quando um número sai do modo gerido, e os números ligados sem URL de webhook começam em modo gerido.
A partir da sua IA, set_inbound_mode muda o modo e define o reenvio numa só chamada, e devolve o segredo do reenvio apenas uma vez:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}O que contém um POST reencaminhado?
Uma alteração da Meta por pedido, num invólucro próprio, em vez do envelope object, entry e changes da Meta. id é o identificador da entrega, repetido em X-EC-Delivery e estável entre tentativas. event é o nome do campo da Meta, messages, smb_message_echoes, history ou smb_app_state_sync, repetido em X-EC-Event. received_at é o momento em que o easyCoexistence recebeu a alteração da Meta, connection identifica o número, e value é exatamente o que a Meta enviou, pelo que o código de análise escrito para o payload da Meta funciona com ele. Os estados de entrega chegam dentro dos eventos messages, em value.statuses.
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}Como verificar o X-EC-Signature em Node.js?
Leia o cabeçalho como t=<segundos unix>,v1=<64 caracteres hexadecimais>. Rejeite um t com mais de 5 minutos de diferença do seu relógio, calcule o HMAC-SHA256 sobre t, um ponto e o corpo bruto, usando todo o segredo de reenvio como texto UTF-8, e compare o resultado com v1 em tempo constante. Só então faça o parse do JSON. Responda 2xx em menos de 10 segundos e faça o trabalho depois, e guarde os identificadores de entrega que aceitou, para que uma nova tentativa não seja processada duas vezes.
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);Como verificar em Python?
As mesmas quatro verificações com a biblioteca padrão: uma expressão regular rigorosa para o cabeçalho, a idade do t, hmac.new sobre t, um ponto e os bytes brutos, e hmac.compare_digest. Em FastAPI o corpo bruto vem de await request.body(), e BackgroundTasks executa o trabalho depois de enviado o 200. Em Flask, use request.get_data(), e nunca reconstrua o corpo com json.dumps, porque os separadores predefinidos do Python acrescentam espaços e a assinatura deixa de corresponder.
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)Como são repetidas as entregas falhadas?
Um reenvio conta como entregue quando o seu endpoint responde com qualquer 2xx em 10 segundos. Qualquer outra resposta, um timeout, um 4xx, um 5xx ou um redirecionamento, que não é seguido, agenda a tentativa seguinte para cerca de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas depois, e após a sétima tentativa a entrega é abandonada. Cada tentativa é assinada de novo com um t novo, e o URL tem de ser HTTPS público, verificado ao guardar e de novo antes de cada envio. As entregas saem da mais antiga para a mais recente, mas uma entrega repetida pode chegar depois de outras mais recentes, por isso ordene pelos carimbos temporais da Meta.
Num destino direto é a Meta que faz as repetições: qualquer resposta diferente de HTTP 200 é repetida com frequência decrescente durante até 7 dias, e essas repetições podem duplicar uma mensagem. Elimine duplicados pelo id de mensagem da Meta nos dois modos, já que uma alteração que a Meta volte a entregar é reenviada com um novo identificador de entrega.
Como é que um endpoint direto sabe que um POST é genuíno?
Não pelo X-Hub-Signature-256. A Meta assina com o segredo da app que é dona da subscrição, que, para um número ligado aqui, é o da app do easyCoexistence e não é partilhado. Verificar esse cabeçalho com o segredo da sua própria app na Meta rejeita entregas genuínas. O token de verificação só prova o endpoint uma vez, durante o handshake GET da Meta. O que funciona em vez disso:
- Coloque 32 ou mais caracteres aleatórios no caminho do URL de callback e rejeite pedidos sem eles; para o substituir, guarde um URL novo.
- Use um recetor genérico, como o nó Webhook do n8n, e não um gatilho do WhatsApp que espere a sua própria app da Meta.
- Transfira os ficheiros multimédia pelo id na Meta com o token do número, para que um id forjado simplesmente falhe.
- Em servidores alojados por si, pode opcionalmente permitir apenas a rede da Meta, as rotas anunciadas pelo AS32934.
- Ou mude para gerido com um Forward URL, onde o X-EC-Signature prova cada POST.
Erros comuns
- Apontar para o Forward URL código escrito para o envelope da Meta sem alterações. Um reenvio traz uma só alteração: leia event e value, não object, entry e changes.
- Esperar um X-EC-Event de statuses. Os estados de entrega chegam dentro dos eventos messages, em value.statuses, e as respostas escritas na app chegam como smb_message_echoes.
- Fazer o trabalho antes de responder. Um reenvio espera 10 segundos, e depois a mesma entrega volta com um t novo; responda 2xx primeiro e processe a partir de uma fila.
- Mudar para gerido e supor que o URL antigo continua a receber. O destino direto é removido nesse momento; passe forward_url na mesma chamada de set_inbound_mode.
O easyCoexistence liga um número da app WhatsApp Business à Cloud API da Meta através da Coexistence e permite escolher, por número, para onde vão as suas mensagens: diretamente da Meta para o seu servidor, ou através do easyCoexistence, para que as automatizações possam responder e uma cópia assinada chegue ao seu Forward URL. A monitorização e os alertas funcionam nos dois modos. De US$ 9 a US$ 0.75 por número ligado por mês, descendo à medida que adiciona números, com os primeiros 3 dias gratuitos.
Perguntas frequentes
O meu servidor vê o que uma automatização respondeu?
Não o texto. A Meta reporta os envios pela API como estados (enviado, entregue, lido) dentro dos eventos messages, com o id da mensagem; o próprio texto está no registo de execução da automatização, guardado 30 dias no separador Execuções, e em Conversas durante o tempo que escolheu.
Como renovo o segredo de reenvio?
Clique em Novo segredo na página do número, ou chame set_inbound_mode com rotate_secret a true. O novo segredo é mostrado apenas uma vez e assina tudo a partir daí, incluindo as repetições de entregas antigas, por isso atualize o seu servidor de imediato.
Um Forward URL precisa do handshake GET da Meta?
Não. Só um destino direto é chamado pela Meta e tem de devolver hub.challenge. Um Forward URL é chamado pelo easyCoexistence e recebe apenas POST assinados.
Um número pode ter um destino direto e um Forward URL ao mesmo tempo?
Não. Um Forward URL só funciona enquanto o número for gerido, e guardar um destino direto torna-o direto. O Forward URL e o respetivo segredo são mantidos, por isso voltar ao modo gerido retoma o reenvio.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em