EntrarComeçar teste grátis
Meta Tech Provider

Como as mensagens do WhatsApp chegam ao seu servidor: direto ou gerenciado, e como verificar a assinatura

Cada número conectado pelo easyCoexistence tem um modo de entrada. Direto para o seu sistema (direto): a Meta envia os webhooks dela ao seu endpoint HTTPS, um segredo na URL serve de credencial e as automações ficam desligadas. Pelo easyCoexistence (gerenciado): a Meta entrega ao easyCoexistence, as automações podem responder e uma Forward URL opcional recebe o value original da Meta com os dados da conexão, assinado com X-EC-Signature para você verificar.

7 attempts

Tentativas por entrega encaminhada, com intervalos de 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 encaminhamento espera por um 2xx antes de ser considerada falha.

5 min

Limite sugerido para a idade do t da assinatura; as repetições são assinadas de novo, então entregas genuínas continuam dentro dele.

7 days

Tempo durante o qual a Meta repete um webhook direto que recebeu qualquer resposta 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

Logs de execução mantidos para um número gerenciado, com o texto das mensagens e das respostas; o texto das mensagens em si é mantido por 30, 90 ou 365 dias, à sua escolha.

Qual é a diferença entre direto e gerenciado?

É onde a Meta entrega os webhooks de mensagens do número. Gerenciado, exibido como Pelo easyCoexistence, significa que a Meta entrega ao easyCoexistence, que verifica a assinatura da Meta, executa suas automações, guarda os chats para Conversas e, se você definir uma Forward URL, repassa cada alteração da Meta para você, assinada com um segredo que só você tem. Direto, exibido como Direto para o seu sistema, significa que o easyCoexistence define o seu endpoint HTTPS como override de webhook na conta do WhatsApp Business do número, então a Meta envia diretamente para você e as mensagens nunca passam pelo easyCoexistence.

Os webhooks operacionais por trás do monitoramento, como account_update e as mudanças de qualidade, continuam com o easyCoexistence nos dois modos, por isso os alertas seguem funcionando em qualquer um deles.

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 alternar um número entre os dois modos?

Na página do número, o cartão Para onde vão as mensagens recebidas mostra o modo como duas opções, Pelo easyCoexistence e Direto para o seu sistema. Salvar um destino de webhook, no cartão Encaminhar mensagens recebidas para o seu próprio webhook ou com set_webhook_destination, torna o número direto. Escolher Pelo easyCoexistence remove esse destino na Meta imediatamente, então adicione a mesma URL como Forward URL para continuar recebendo. Os encaminhamentos na fila são descartados quando um número sai do modo gerenciado, e números conectados sem URL de webhook começam como gerenciados.

Pela sua IA, set_inbound_mode troca o modo e define o encaminhamento em uma só chamada, e retorna o segredo de encaminhamento uma única 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 um POST encaminhado contém?

Uma alteração da Meta por requisição, encapsulada, em vez do envelope object, entry e changes da Meta. id é o ID da entrega, repetido em X-EC-Delivery e estável entre as 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, então o código de parsing escrito para o payload da Meta funciona com ele. Os status de entrega chegam dentro de 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 no Node.js?

Leia o cabeçalho no formato 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 como chave o segredo de encaminhamento completo como texto UTF-8, e compare o resultado com v1 em tempo constante. Só então faça o parse do JSON. Responda com 2xx em até 10 segundos e faça o processamento depois, e guarde os IDs de entrega que você já aceitou para que uma repetição 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: um padrão estrito para o cabeçalho, a idade do t, hmac.new sobre t, um ponto e os bytes brutos, e hmac.compare_digest. No FastAPI, o corpo bruto vem de await request.body(), e BackgroundTasks executa o processamento depois que o 200 é enviado. No Flask, use request.get_data() e nunca reconstrua o corpo com json.dumps, porque os separadores padrão do Python adicionam espaços e a assinatura deixa de bater.

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 as entregas com falha são repetidas?

Um encaminhamento conta como entregue quando o seu endpoint responde qualquer 2xx em até 10 segundos. Qualquer outra resposta, seja um timeout, um 4xx, um 5xx ou um redirecionamento, que não é seguido, agenda a próxima tentativa 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 a URL precisa ser HTTPS pública, verificada ao ser salva e de novo antes de cada envio. As entregas saem da mais antiga para a mais nova, mas uma entrega repetida pode chegar depois de outras mais novas, então ordene pelos timestamps da Meta.

Em um destino direto, quem repete é a Meta: qualquer resposta diferente de HTTP 200 é repetida com frequência decrescente por até 7 dias, e essas repetições podem duplicar uma mensagem. Deduplique pelo ID de mensagem da Meta nos dois modos, já que uma alteração que a Meta reenvia é encaminhada de novo com um novo ID de entrega.

Como um endpoint direto sabe que um POST é genuíno?

Não pelo X-Hub-Signature-256. A Meta assina com o app secret do app dono da assinatura, que, para um número conectado aqui, é o do easyCoexistence e não é compartilhado; por isso, verificar esse cabeçalho com o app secret do seu próprio app da Meta rejeita entregas genuínas. O verify token só valida o endpoint uma vez, durante o handshake GET da Meta. O que funciona no lugar disso:

  • Coloque 32 ou mais caracteres aleatórios no caminho da URL de callback e rejeite requisições sem eles; para trocá-los, salve uma nova URL.
  • Use um receptor genérico, como o nó Webhook do n8n, e não um gatilho do WhatsApp que espera o seu próprio app da Meta.
  • Baixe a mídia pelo ID na Meta com o token do número, para que um ID forjado simplesmente falhe.
  • Em servidores self-hosted, opcionalmente permita apenas a rede da Meta, as rotas anunciadas pelo AS32934.
  • Ou mude para o modo gerenciado com uma Forward URL, em que o X-EC-Signature comprova cada POST.

Erros comuns

  • Apontar para a Forward URL, sem mudanças, um código escrito para o envelope da Meta. Um encaminhamento traz uma única alteração: leia event e value, não object, entry e changes.
  • Esperar um X-EC-Event de statuses. Os status de entrega vêm dentro de eventos messages, em value.statuses, e as respostas digitadas no app chegam como smb_message_echoes.
  • Fazer o processamento antes de responder. Um encaminhamento espera 10 segundos e depois a mesma entrega volta com um novo t; responda 2xx primeiro e processe a partir de uma fila.
  • Mudar para gerenciado achando que a URL antiga continua recebendo. O destino direto é removido nesse momento; passe forward_url na mesma chamada de set_inbound_mode.
Fazendo isso com o EasyCoexistence

O easyCoexistence conecta um número do app do WhatsApp Business à Cloud API da Meta por meio da Coexistência e deixa você escolher, por número, para onde vão as mensagens: direto da Meta para o seu servidor ou pelo easyCoexistence, para que as automações possam responder e uma cópia assinada chegue à sua Forward URL. Monitoramento e alertas funcionam nos dois modos. De US$ 9 até US$ 0,75 por número por mês, caindo conforme você adiciona números, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Meu servidor vê o que uma automação respondeu?

Não o texto. A Meta informa os envios pela API como status (enviado, entregue, lido) dentro de eventos messages, com o ID da mensagem; o texto em si fica no log de execução da automação, mantido por 30 dias na aba Execuções, e em Conversas pelo tempo que você escolheu.

Como trocar o segredo de encaminhamento?

Clique em Novo segredo na página do número ou chame set_inbound_mode com rotate_secret definido como true. O novo segredo é mostrado uma única vez e assina tudo a partir daí, inclusive as repetições de entregas antigas, então atualize o seu servidor imediatamente.

Uma Forward URL precisa do handshake GET da Meta?

Não. Só um destino direto é chamado pela Meta e precisa devolver o hub.challenge. Uma Forward URL é chamada pelo easyCoexistence e recebe apenas POSTs assinados.

Um número pode ter um destino direto e uma Forward URL ao mesmo tempo?

Não. Uma Forward URL só funciona enquanto o número está no modo gerenciado, e salvar um destino direto torna o número direto. A Forward URL e o seu segredo são mantidos, então voltar ao modo gerenciado retoma o encaminhamento.

Continue lendo

Pronto para começar?

Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.

Começar teste grátis

Verificado em