Iniciar sesiónEmpezar prueba gratis
Meta Tech Provider

Reintentos, duplicados y orden de los webhooks de WhatsApp: cómo gestionarlos

Meta reintenta un webhook de WhatsApp que recibe cualquier respuesta distinta de HTTP 200, primero de inmediato y luego con frecuencia decreciente durante un máximo de 7 días, y después lo descarta. Los reintentos llegan a todas las apps suscritas a la cuenta, así que los duplicados son normales. Responde 200 rápido, deduplica por el id del mensaje o por el id de status junto con el propio status, y ordena los eventos por sus propios timestamps.

easyCoexistence conecta el número de tu app de WhatsApp Business con la Cloud API de Meta mediante Coexistencia y absorbe las entregas repetidas de Meta antes de que lleguen a tus automatizaciones, así que un mensaje reintentado no recibe una segunda respuesta de IA.

7 days

Cuánto tiempo sigue Meta reintentando un webhook que no recibió HTTP 200, antes de descartarlo.

1,000

Máximo de actualizaciones que Meta agrupa en un solo POST; Meta no garantiza el agrupamiento, así que procesa cada petición por separado.

3 MB

Tamaño máximo del payload que puede llevar un POST de webhook de WhatsApp.

7 days

Cuánto tiempo recuerda easyCoexistence el id de cada mensaje entrante, para que un mensaje entregado de nuevo no ejecute una automatización dos veces.

7 attempts

Intentos por cada reenvío a tu Forward URL, cada uno esperando 10 segundos un 2xx, durante unas 33 horas.

¿Cuándo reintenta Meta un webhook de WhatsApp?

Siempre que una entrega a tu endpoint recibe un estado HTTP distinto de 200, o directamente no se puede entregar. Meta reintenta de inmediato, luego algunas veces más con frecuencia decreciente durante los 7 días siguientes, y después descarta lo que siga sin confirmar. Los reintentos llegan a todas las apps suscritas a la WhatsApp Business Account para ese campo, y por eso Meta advierte que pueden generar notificaciones duplicadas. No existe ninguna API para obtener webhooks pasados, así que una entrega que agota sus 7 días se pierde para tu sistema.

¿Por qué llegan duplicados aunque tu servidor funcione bien?

Porque una entrega puede salir bien de tu lado y aun así parecer fallida para Meta. Un handler que hace su trabajo antes de responder puede superar el tiempo de espera de Meta, y entonces Meta reintenta algo que ya procesaste. Un despliegue que reinicia el servidor a mitad de una petición, un balanceador de carga que devuelve 502 por un momento o un 201 o 204 en lugar de 200 cuentan como fallos. Los lotes añaden un caso más: un POST puede contener muchas actualizaciones, así que un timeout en un lote grande hace que vuelva el lote entero, incluidas las actualizaciones que ya procesaste.

¿Por qué clave conviene deduplicar?

Por los ids propios de Meta, elegidos según el tipo de evento, porque un mismo mensaje genera legítimamente varios webhooks. Una clave de status sin el valor del status descartaría delivered y read como copias de sent, y una clave de llamada sin el evento conservaría solo la primera etapa de la llamada. Guarda las claves con un índice único, para que dos workers que procesen el mismo reintento no puedan imponerse los dos:

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

¿En qué orden llegan los webhooks?

No necesariamente en el orden en que ocurrieron las cosas. La documentación de Meta no garantiza ningún orden, una entrega reintentada llega después de otras más recientes y un status puede saltarse un paso: Meta envía read sin delivered cuando un mensaje se lee en el mismo momento en que llega. Por eso, guarda los eventos con su propio campo de timestamp, compara cada status por su rango y no por su llegada, y haz que un mensaje posterior del cliente prevalezca sobre uno anterior que llegó con retraso. En un número con Coexistencia, la importación única del historial puede solaparse con los mensajes en vivo durante el onboarding, y el id del mensaje es lo que permite conciliar ambos.

¿Cómo es un handler seguro?

Cuatro pasos: verificar, responder exactamente 200, deduplicar y después trabajar desde una cola, para que nada lento se interponga entre la petición de Meta y tu respuesta. Esta versión comprueba X-Hub-Signature-256 con el secreto de tu propia app de Meta; en un número conectado a través de easyCoexistence, Meta firma con el secreto de la app de easyCoexistence, así que un destino directo se autentica en su lugar con un secreto largo en la ruta de su URL, o pasa al reenvío gestionado con firma por número.

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production

// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
  const keys = [];
  for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
  for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
  for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
  for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
  return keys;
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
    const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
    if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // exactly 200, before any work
    const body = JSON.parse(raw.toString("utf8"));
    for (const entry of body.entry ?? []) {
      for (const change of entry.changes ?? []) {
        for (const key of keysOf(change.field, change.value ?? {})) {
          if (seen.has(key)) continue; // a retry of something already accepted
          seen.add(key);
          // queue { key, field: change.field, value: change.value } for a worker here
          console.log("new", key);
        }
      }
    }
  });
}).listen(process.env.PORT ?? 3000);

¿Cómo gestiona easyCoexistence los reintentos en un número conectado?

A la entrada, easyCoexistence verifica la firma de Meta, responde 200 y ejecuta las automatizaciones después de responder, así que Meta no reintenta porque una respuesta de IA haya tardado unos segundos. Cada id de mensaje entrante se guarda durante 7 días, lo que dura la ventana de reintentos de Meta, y un mensaje entregado de nuevo se reconoce y no dispara una segunda respuesta automática.

A la salida hacia tu Forward URL, cada cambio de Meta se convierte en una entrega con un id en X-EC-Delivery que se mantiene igual en todos los reintentos del reenvío: 7 intentos durante unas 33 horas, cada uno esperando 10 segundos un 2xx. Un cambio que el propio Meta vuelve a entregar se reenvía de nuevo con un id de entrega nuevo, así que deduplica también por los ids de Meta dentro de value.

Errores comunes

  • Deduplicar los statuses solo por id. sent, delivered y read comparten el wamid, así que la clave también necesita el status.
  • Procesar antes de responder. Un handler lento hace que Meta reintente un trabajo que ya hiciste; devuelve 200 primero y trabaja desde una cola.
  • Devolver 201 o 204. La documentación de Meta trata cualquier estado distinto de 200 como una entrega fallida y la reintenta.
  • Deduplicar los reenvíos solo por X-EC-Delivery. Un cambio que Meta vuelve a entregar llega con un id de entrega nuevo; usa los ids de Meta como segunda clave.
Hacerlo con EasyCoexistence

Los reenvíos a tu servidor se firman, se encolan y se reintentan, y cada número se supervisa 24/7. De US$ 9 a US$ 0.75 por número al mes, bajando a medida que añades números, con los primeros 3 días gratis.

Preguntas frecuentes

¿Cuánto tiempo debo guardar los ids que ya he recibido?

Al menos 7 días, la ventana de reintentos de Meta. Una entrega que Meta reintenta el sexto día tiene que seguir coincidiendo con su clave; si no, se procesará como nueva.

¿Qué pasa con los mensajes de mis clientes si mi endpoint está caído varios días?

Meta reintenta durante un máximo de 7 días y luego descarta los webhooks. En un número con Coexistencia, las conversaciones siguen en la app de WhatsApp Business del teléfono, así que el negocio puede responder desde ahí.

¿Puedo volver a recibir los webhooks que me perdí?

No desde Meta: no existe ninguna API para datos históricos de webhooks. La importación única del historial de un número con Coexistencia solo se ejecuta durante el onboarding y no se puede volver a solicitar para la misma conexión.

¿Meta envía la misma actualización a más de un servidor?

La envía a todas las apps suscritas a la WhatsApp Business Account para ese campo. Con un override de destino, los campos de mensajes del número van a la URL del override en lugar de al callback predeterminado de esa app.

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