Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

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.

7 attempts

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.

10 s

Tempo que cada tentativa de reenvio espera por um 2xx antes de ser considerada falhada.

5 min

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.

7 days

Tempo durante o qual a Meta repete um webhook direto que recebeu algo diferente de HTTP 200, o que pode repetir mensagens.

3 MB

Maior payload de webhook enviado pela Meta, incluindo os blocos de histórico.

30 days

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 easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

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 and result
// 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.

A forwarded messages event: headers and body
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.js, no dependencies)
// 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 (FastAPI)
# 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.
Fazer isto com a EasyCoexistence

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 gratuito

Verificado em