Webhook de Messenger para Páginas de Facebook: mensajes y menciones de eventos
El campo messages de los webhooks de Página de Facebook se activa cuando una persona envía a la Página un mensaje de Messenger, y entrega un arreglo messaging con el ID del remitente con alcance de Página, el ID de la Página, una marca de tiempo y el mid del mensaje con su texto o adjuntos. El campo mention informa de nuevas menciones de la Página en publicaciones y comentarios, y Meta firma ambos con X-Hub-Signature-256.
easyCoexistence reenvía los mensajes y menciones de Messenger de cada Página conectada a tu endpoint HTTPS a medida que llegan, firmados con un secreto de esa Página y sin copia guardada, y send_social_dm responde dentro de la ventana de 24 horas.
Con qué rapidez pide Meta a un endpoint de webhook de Messenger que responda 200 OK a cada notificación.
Si las entregas fallan durante este tiempo, Meta cancela la suscripción de la app a los webhooks de la Página hasta que vuelva a suscribirse.
El ID del remitente con alcance de Página en un evento messages, único para cada par de persona y Página.
Cómo marca la referencia de Meta el campo sender de un evento de mención.
Las notificaciones de webhook pasadas no se pueden consultar después, así que el receptor debe guardar lo que necesite.
¿Qué envía el campo messages?
Una notificación cuando una persona envía a la Página un mensaje de Messenger. Meta envía mensajes de texto o mensajes con adjuntos, que pueden ser imágenes, audio, video, archivos o stickers, entre otros tipos, y un enlace compartido puede llegar como adjunto de respaldo. Una respuesta a un mensaje anterior trae reply_to con el mid de ese mensaje, y una respuesta rápida trae su payload.
¿Cómo es un evento messages?
A diferencia de los cambios de feed, un mensaje llega en un arreglo messaging dentro de entry de la Página. Cada evento tiene sender, el ID del remitente con alcance de Página; recipient, la Página; una marca de tiempo; y message, con su mid y text, o attachments con un type y una URL de payload:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}¿Qué envía el campo mention?
Un cambio cuyo field es mention cuando se menciona la Página en una publicación o un comentario, con post_id o comment_id, el mensaje, cualquier enlace, foto o video, y item y verb. Meta advierte que algunos de esos IDs de publicación y comentario no se pueden consultar, por falta de permiso o por privacidad, y su referencia marca el campo sender solo para Workplace, así que una mención puede llegar sin su autor.
¿Qué campos de Messenger no se reenvían?
easyCoexistence suscribe las Páginas a messages, no a message_echoes, messaging_postbacks, message_reads ni message_deliveries, así que no se reenvían los mensajes que envía la Página, los toques en botones ni los recibos de lectura o entrega. Una respuesta enviada con send_social_dm devuelve su propio ID de mensaje en su lugar.
¿Cómo llegan los eventos a tu endpoint?
Meta entrega los webhooks de Página a la app que la Página instaló, mediante una única URL de callback para toda la app. easyCoexistence verifica X-Hub-Signature-256 de Meta en cada entrega, responde a Meta de inmediato y reenvía cada entrada de una Página conectada al endpoint HTTPS que configuraste para ella, firmado con el secreto propio de esa Página. Configúralo con set_social_webhook_destination desde Claude o ChatGPT, o con PUT /channels/:id/webhook en la Partner API; el secreto se muestra una sola vez, volver a configurarlo emite uno nuevo, y una URL null desactiva el reenvío.
¿Cómo es un evento reenviado?
Un POST que contiene la plataforma, el account_id que devuelve list_social_accounts para la conexión de la Página, el ID de la Página como external_id, y entry: la entrada de Meta para la Página, sin cambios. sender.id es el recipient_id que toma send_social_dm para responder dentro de la ventana de 24 horas:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}¿Cómo verificas un evento reenviado?
Cada POST reenviado trae un encabezado X-EC-Signature con la forma t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, usando como clave el secreto de firma de la Página. Calcúlalo sobre el cuerpo exactamente como llegó, compara en tiempo constante y rechaza una marca de tiempo con más de 5 minutos de antigüedad.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}¿Se reintenta una entrega?
No por parte de easyCoexistence. Cada entrada se reenvía una sola vez, en memoria, sin copia guardada desde la que reintentar; el reenvío espera 8 segundos una respuesta, no sigue redirecciones y solo va a una dirección HTTPS que resuelve a una IP pública. Meta indica que las notificaciones pasadas no se pueden consultar después, así que guarda lo que necesites a medida que llega. Aguas arriba, Meta reintenta de inmediato una entrega fallida varias veces, así que el mismo mensaje puede llegarte dos veces de vez en cuando: deduplica por su mid.
Errores comunes
- Hacer el trabajo antes de responder. El reenvío no reintenta, así que devuelve un 2xx de inmediato y procesa el evento después.
- Verificar la firma sobre JSON ya parseado. Calcula el HMAC sobre el cuerpo sin procesar exactamente como llegó.
- Asumir que un mensaje siempre tiene texto. Un sticker, una imagen o un enlace compartido llega como attachments, sin campo text.
- Omitir la deduplicación. Meta puede volver a entregar un evento tras un fallo, así que usa el mid del mensaje como clave antes de actuar.
Activa el reenvío con set_social_webhook_destination o con la Partner API. 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
¿A qué campos de webhook suscribe easyCoexistence una Página?
messages para Messenger y mention para menciones, junto a feed para las publicaciones y comentarios de la Página.
¿Un sticker o una imagen de Messenger llega con texto?
No. Un sticker, una imagen o un enlace compartido llega en attachments, cada uno con un type y una URL de payload, y el mensaje no tiene campo text.
¿Con qué rapidez debe responder un endpoint de webhook de Messenger?
Con 200 OK en un plazo de 5 segundos. Tras 1 hora de entregas fallidas, Meta cancela la suscripción de la app a los webhooks de la Página.
¿Cómo respondo a un mensaje reenviado?
Llama a send_social_dm con el sender.id del evento como recipient_id, dentro de las 24 horas del mensaje de la persona.
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