Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Cómo recibir los mensajes de WhatsApp y los comentarios de redes sociales de tus clientes por webhook

Cada conexión recibe su propio webhook para los mensajes de WhatsApp o los comentarios de redes sociales de tus clientes a través de la Partner API de easyCoexistence. Los mensajes de WhatsApp van de Meta directamente a esa URL, firmados con el secreto de la app Tech Provider y no con uno que tú poseas, así que un secreto largo y aleatorio en la ruta de la URL los autentica. Los comentarios y DMs de Instagram y Facebook, y los comentarios de TikTok, se reenvían en cuanto llegan, firmados por cuenta con X-EC-Signature.

200 characters

Longitud máxima que Meta permite para la URL de callback alternativa que envía los mensajes de un número a tu endpoint.

7 days

Cuánto tiempo reintenta Meta un webhook de WhatsApp que tu endpoint no aceptó, con frecuencia decreciente, lo que puede producir duplicados.

AS32934

La red de Meta; las búsquedas whois de rutas la listan con las direcciones desde las que llegan los webhooks de WhatsApp, que Meta cambia periódicamente.

3 MB

El tamaño máximo de un payload de webhook de WhatsApp, según Meta.

5 minutes

Antigüedad a partir de la cual debe rechazarse el timestamp firmado de un evento reenviado, y el HMAC se compara en tiempo constante.

¿Cómo obtiene cada conexión su propio destino?

Mediante una llamada por recurso. Un número de WhatsApp usa PUT /connections/{id}/webhook con una url y un verify_token, o el mismo par como webhook_url y webhook_verify_token en su sesión de conexión, de modo que el número te envía eventos desde el primer minuto. Una cuenta social usa PUT /channels/{id}/webhook una vez conectada. Una url de null en cualquiera de los dos desactiva la entrega. Las dos vías se diferencian en quién entrega y en cómo autenticas:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

¿Cómo diriges los mensajes de un número a tu endpoint?

Indica una URL HTTPS cuya ruta contenga un secreto largo y aleatorio, más un verify token: webhook_verify_token en una sesión de conexión, de 8 a 200 caracteres, o verify_token en el PUT. Meta comprueba la URL de inmediato con un GET que lleva hub.mode=subscribe, hub.verify_token y hub.challenge, y tu endpoint debe responder con el valor de hub.challenge cuando el token coincida. Si esa verificación falla, el PUT devuelve 502 meta_rejected con el mensaje propio de Meta; en una sesión de conexión el número se conecta igualmente y el last_error de la sesión indica por qué no se aplicó la URL.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

¿Por qué no puedes verificar la firma de Meta y qué la sustituye?

Meta firma cada entrega con X-Hub-Signature-256, un HMAC-SHA256 del payload con la App Secret de la app receptora. En el caso de los números de tus clientes, esa app es la app Tech Provider de easyCoexistence, cuyo secreto nunca se comparte, así que el encabezado no se puede verificar de tu lado. La credencial es el secreto largo y aleatorio de la ruta de la URL: compáralo en tiempo constante y rechaza cualquier otra cosa. Como segunda capa, incluye en una lista de permitidos las rutas registradas a nombre de Meta en AS32934 y actualiza esa lista, ya que Meta cambia sus direcciones IP periódicamente.

¿Qué webhooks de WhatsApp llegan a tu URL?

Los campos que una URL de callback alternativa puede llevar: messages, para lo que envían tus clientes y el estado de lo que tú envías; smb_message_echoes, para lo que el negocio envía desde la app de WhatsApp Business; y el historial de la importación única y smb_app_state_sync. Meta nunca envía a esa URL alternativa los webhooks de plantilla ni los de cuenta como account_update. Estos llegan al callback de easyCoexistence, por eso la revisión de plantillas se lee por sondeo y una baja llega como evento de estado.

  • El destino se configura en la cuenta de WhatsApp Business, así que dos números de una misma cuenta lo comparten: enruta por value.metadata.phone_number_id.
  • Los archivos multimedia llegan como ID; descarga el archivo de Meta con el token del cliente de la llamada de credenciales.
  • Los payloads pueden alcanzar 3 MB, así que eleva cualquier límite de tamaño del cuerpo configurado por debajo de eso.

¿Cómo es un evento social reenviado?

Un POST con Content-Type application/json y un encabezado X-EC-Signature, con cuatro claves: platform; account_id, el ID del canal que usa la Partner API; external_id, el ID de la cuenta en la red; y entry. En Instagram y Facebook, entry es la entrada del webhook de Meta sin cambios, con changes para comentarios y menciones y messaging para los DMs. En TikTok contiene el evento comment.update con su contenido parseado, y comment_id, video_id y parent_comment_id como cadenas, para que los IDs de 64 bits no se redondeen.

  • Las cuentas de Instagram se suscriben a comments, messages y mentions; las Páginas de Facebook a feed, messages y mention; TikTok envía comment.update.
  • easyCoexistence no recibe eventos de comentarios de YouTube ni de LinkedIn: su PUT responde 400 not_supported, y sus comentarios se leen mediante la API de cada red con las credenciales.
  • Los reenvíos no llevan encabezado X-EC-Event ni X-EC-Delivery, así que deduplica con los IDs propios de cada red, como un ID de comentario o un mid de mensaje.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

¿Cómo verificas X-EC-Signature, paso a paso?

Con el signing_secret que devolvió PUT /channels/{id}/webhook, que se muestra una sola vez y es único para esa cuenta. El encabezado tiene el formato t=<unix>,v1=<hex>. Luego, para cada entrega:

  • Lee el cuerpo bruto de la petición como bytes, antes de cualquier parseo JSON.
  • Separa el encabezado por comas en t, una hora Unix en segundos, y v1, un digest hexadecimal.
  • Rechaza la entrega si t está a más de 5 minutos de tu reloj.
  • Calcula HMAC-SHA256 sobre t, un punto y el cuerpo bruto, con la clave secreta de esa cuenta, en hexadecimal.
  • Compara con v1 en tiempo constante y luego responde 2xx y encola el trabajo.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

¿Qué pasa cuando no hay destino configurado?

No te llega nada, y nada queda en espera para enviarse más tarde. Un número sin webhook_url recurre al callback de easyCoexistence, donde sus mensajes se descartan sin guardarse, y no recibe importación de historial de chat, que solo se solicita cuando existe un destino. Una cuenta social sin destino no se reenvía: sus eventos siguen llegando a la app de easyCoexistence, pero no se retiene ninguno para ti. Configura cada destino antes de que necesites el tráfico.

¿Qué pasa con un destino cuando una conexión se cae o se elimina?

Un número conserva su destino registrado. Cuando un número caído se reconecta, easyCoexistence vuelve a configurar tu URL en Meta, y lo mismo ocurre cuando un número suspendido regresa. Eliminar una cuenta social borra su destino y su secreto, así que tras reconectarla vuelve a llamar a PUT /channels/{id}/webhook y guarda el nuevo secreto. Ese PUT emite un secreto nuevo cada vez que se llama con una URL, y el anterior deja de firmar de inmediato.

Cómo configurarlo

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Errores comunes

  • Verificar X-Hub-Signature-256 en las entregas de WhatsApp de tus clientes. Meta la calcula con la app secret de easyCoexistence, que nunca se comparte, así que la comprobación nunca pasará; autentica con el secreto de la ruta de la URL.
  • Verificar X-EC-Signature sobre JSON ya parseado. El HMAC cubre el cuerpo bruto byte a byte, y volver a serializarlo cambia los bytes, así que verifica antes de parsear.
  • Usar un solo secreto para todos los canales. Cada cuenta social firma con su propio secreto, y los eventos de estado con otro, así que busca el secreto por account_id.
  • Hacer trabajo lento antes de responder a un evento reenviado. Se envía una vez, espera 8 segundos tu respuesta y nunca se reintenta, así que responde 2xx primero y procesa después.
Hacerlo con EasyCoexistence

easyCoexistence enruta los mensajes de cada número de cliente desde Meta directamente a tu servidor, y reenvía a tu endpoint los comentarios y DMs de Instagram y Facebook, y los comentarios de TikTok, en cuanto llegan, firmados por cuenta, sin copia guardada y con cada conexión monitorizada las 24 horas. De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿Puedo verificar la firma de Meta en los mensajes de WhatsApp de mis clientes?

No. Meta los firma con el secreto de la app Tech Provider de easyCoexistence, que nunca se comparte. Autentica con el secreto largo y aleatorio de la ruta de tu URL y, opcionalmente, con los rangos IP de Meta.

¿Las conexiones de YouTube y LinkedIn reenvían eventos de comentarios?

No. easyCoexistence no recibe eventos de comentarios de ninguna de las dos, así que PUT /channels/{id}/webhook responde 400 not_supported. Lee sus comentarios mediante la API de cada red con las credenciales del canal.

¿Se reintentan los eventos sociales reenviados si mi servidor está caído?

No. Cada uno se envía una vez y no se guarda copia. Las entregas de WhatsApp son distintas, porque el propio Meta las reintenta durante hasta 7 días.

¿Los mensajes pasan por easyCoexistence?

No en WhatsApp: Meta entrega los mensajes de un número directamente al webhook que configuras. Los comentarios y DMs de las redes sociales se reenvían a tu endpoint en cuanto llegan, firmados por cuenta, sin copia guardada.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el