Iniciar sesiónEmpezar prueba gratis
Meta Tech Provider

Cómo llegan los mensajes de WhatsApp a tu servidor: directo o gestionado, y cómo verificar la firma

Cada número conectado mediante easyCoexistence tiene un único modo de entrada. Directo a tu sistema (directo): Meta envía sus webhooks a tu endpoint HTTPS, un secreto en la URL sirve de credencial y las automatizaciones quedan desactivadas. A través de easyCoexistence (gestionado): Meta los entrega a easyCoexistence, las automatizaciones pueden responder y una Forward URL opcional recibe el value original de Meta con los datos de la conexión, firmado con X-EC-Signature para que lo verifiques.

7 attempts

Intentos por entrega reenviada, espaciados 1 min, 5 min, 30 min, 2 h, 6 h y 24 h, unas 33 horas en total.

10 s

Cuánto espera cada intento de reenvío una respuesta 2xx antes de darse por fallido.

5 min

Límite sugerido para la antigüedad del t de la firma; los reintentos se firman de nuevo, así que las entregas legítimas quedan dentro de ese margen.

7 days

Durante cuánto tiempo reintenta Meta un webhook directo que recibió una respuesta distinta de HTTP 200, lo que puede repetir mensajes.

3 MB

Tamaño máximo del payload de webhook que envía Meta, incluidos los fragmentos del historial.

30 days

Registros de ejecución conservados para un número gestionado, con el texto de los mensajes y las respuestas; el propio texto de los mensajes se conserva 30, 90 o 365 días, a tu elección.

¿Qué diferencia hay entre el modo directo y el gestionado?

Dónde entrega Meta los webhooks de mensajes del número. Gestionado, que aparece como A través de easyCoexistence, significa que Meta entrega a easyCoexistence, que comprueba la firma de Meta, ejecuta tus automatizaciones, guarda los chats para Conversaciones y, si configuras una Forward URL, te reenvía cada cambio de Meta firmado con un secreto que solo tú conoces. Directo, que aparece como Directo a tu sistema, significa que easyCoexistence configura tu endpoint HTTPS como override del webhook en la cuenta de WhatsApp Business del número, de modo que Meta te envía los POST directamente y los mensajes nunca pasan por easyCoexistence.

Los webhooks operativos en los que se basa el monitoreo, como account_update y los cambios de calidad, siguen llegando a easyCoexistence en ambos modos, y por eso las alertas funcionan en cualquiera de los dos.

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

¿Cómo se cambia un número de un modo a otro?

En la página del número, la tarjeta Adónde van los mensajes entrantes muestra el modo como dos opciones, A través de easyCoexistence y Directo a tu sistema. Guardar un destino de webhook, en la tarjeta Enviar mensajes entrantes a tu propio webhook o con set_webhook_destination, pasa el número a directo. Elegir A través de easyCoexistence elimina ese destino en Meta en el acto, así que añade la misma URL como Forward URL para seguir recibiendo. Los reenvíos en cola se descartan cuando un número sale del modo gestionado, y los números conectados sin URL de webhook empiezan en modo gestionado.

Desde tu IA, set_inbound_mode cambia el modo y configura el reenvío en una sola llamada, y devuelve el secreto del reenvío una ú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
}

¿Qué contiene un POST reenviado?

Cada petición lleva un solo cambio de Meta, envuelto, en lugar del sobre object, entry y changes de Meta. id es el id de la entrega, se repite en X-EC-Delivery y no cambia entre reintentos. event es el nombre del campo de Meta (messages, smb_message_echoes, history o smb_app_state_sync) y se repite en X-EC-Event. received_at es el momento en que easyCoexistence recibió el cambio de Meta, connection identifica el número y value es exactamente lo que envió Meta, así que el código escrito para el payload de Meta funciona con él. Los estados de entrega llegan dentro de los eventos messages, en 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?" }
    }]
  }
}

¿Cómo se verifica X-EC-Signature en Node.js?

Lee el encabezado con el formato t=<segundos unix>,v1=<64 caracteres hexadecimales>. Rechaza un t que se aleje más de 5 minutos de tu reloj, calcula HMAC-SHA256 sobre t, un punto y el cuerpo sin procesar, usando como clave el secreto del reenvío completo como texto UTF-8, y compara el resultado con v1 en tiempo constante. Solo entonces analiza el JSON. Responde con un 2xx en menos de 10 segundos y haz el trabajo después, y guarda los ids de entrega que ya aceptaste para no procesar dos veces un reintento.

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);

¿Cómo se verifica en Python?

Las mismas cuatro comprobaciones con la biblioteca estándar: un patrón estricto para el encabezado, la antigüedad de t, hmac.new sobre t, un punto y los bytes sin procesar, y hmac.compare_digest. En FastAPI el cuerpo sin procesar se obtiene con await request.body(), y BackgroundTasks ejecuta el trabajo después de enviar el 200. En Flask, usa request.get_data() y nunca reconstruyas el cuerpo con json.dumps, porque los separadores por defecto de Python añaden espacios y la firma deja de coincidir.

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)

¿Cómo se reintentan las entregas fallidas?

Un reenvío se considera entregado cuando tu endpoint responde con cualquier 2xx en menos de 10 segundos. Cualquier otra respuesta (un tiempo de espera agotado, un 4xx, un 5xx o una redirección, que no se sigue) programa el siguiente intento aproximadamente 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas después, y tras el séptimo intento la entrega se abandona. Cada intento se firma de nuevo con un t nuevo, y la URL debe ser HTTPS pública, algo que se comprueba al guardarla y otra vez antes de cada envío. Las entregas salen de la más antigua a la más reciente, pero una reintentada puede llegar después de otras más nuevas, así que ordena por las marcas de tiempo de Meta.

En un destino directo, los reintentos los hace Meta: cualquier respuesta distinta de HTTP 200 se reintenta con frecuencia decreciente durante un máximo de 7 días, y esos reintentos pueden repetir un mensaje. Deduplica por el id de mensaje de Meta en ambos modos, ya que un cambio que Meta vuelve a entregar se reenvía con un id de entrega nuevo.

¿Cómo sabe un endpoint directo que un POST es legítimo?

No por X-Hub-Signature-256. Meta firma con el app secret de la app propietaria de la suscripción, que para un número conectado aquí es la de easyCoexistence y no se comparte, así que comprobar ese encabezado con el app secret de tu propia app de Meta rechaza entregas legítimas. El verify token solo valida el endpoint una vez, durante el handshake GET de Meta. Lo que sí funciona:

  • Pon 32 o más caracteres aleatorios en la ruta de la URL de callback y rechaza las peticiones que no los incluyan; para rotarlos, guarda una URL nueva.
  • Usa un receptor genérico, como el nodo Webhook de n8n, y no un disparador de WhatsApp que espere tu propia app de Meta.
  • Descarga los archivos multimedia por id desde Meta con el token del número; así, un id falsificado simplemente falla.
  • En servidores autoalojados, permite opcionalmente solo la red de Meta, es decir, las rutas anunciadas por AS32934.
  • O cambia a gestionado con una Forward URL, donde X-EC-Signature acredita cada POST.

Errores comunes

  • Apuntar a la Forward URL, sin cambios, código escrito para el sobre de Meta. Un reenvío lleva un solo cambio: lee event y value, no object, entry ni changes.
  • Esperar un X-EC-Event de tipo statuses. Los estados de entrega llegan dentro de los eventos messages, en value.statuses, y las respuestas escritas en la app llegan como smb_message_echoes.
  • Hacer el trabajo antes de responder. Un reenvío espera 10 segundos y después la misma entrega vuelve con un t nuevo; responde 2xx primero y procesa desde una cola.
  • Cambiar a gestionado y dar por hecho que la URL anterior sigue recibiendo. El destino directo se elimina en ese momento; pasa forward_url en la misma llamada a set_inbound_mode.
Hacerlo con EasyCoexistence

easyCoexistence conecta un número de la app de WhatsApp Business a la Cloud API de Meta mediante Coexistencia y te permite elegir, número por número, adónde van sus mensajes: directo de Meta a tu servidor, o a través de easyCoexistence para que las automatizaciones respondan y una copia firmada llegue a tu Forward URL. El monitoreo y las alertas funcionan en ambos modos. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que añades números, con los primeros 3 días gratis.

Preguntas frecuentes

¿Mi servidor ve lo que respondió una automatización?

El texto no. Meta informa de los envíos hechos por la API como estados (sent, delivered, read) dentro de los eventos messages, con el id del mensaje; el texto en sí está en el registro de ejecución de la automatización, que se conserva 30 días en la pestaña Runs, y en Conversaciones durante el tiempo que elegiste.

¿Cómo roto el secreto del reenvío?

Haz clic en Nuevo secreto en la página del número o llama a set_inbound_mode con rotate_secret en true. El nuevo secreto se muestra una sola vez y firma todo a partir de ese momento, incluidos los reintentos de entregas anteriores, así que actualiza tu servidor de inmediato.

¿Una Forward URL necesita el handshake GET de Meta?

No. Solo a un destino directo lo llama Meta, y debe devolver hub.challenge. A la Forward URL la llama easyCoexistence y solo recibe POST firmados.

¿Puede un número tener a la vez un destino directo y una Forward URL?

No. La Forward URL solo funciona mientras el número está en modo gestionado, y guardar un destino directo lo pasa a directo. La Forward URL y su secreto se conservan, así que al volver a gestionado se reanuda el reenvío.

Sigue leyendo

¿Listo para empezar?

Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.

Empezar prueba gratis

Verificado el