Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Eventos webhook de Instagram: comentarios, menciones y DMs

Los eventos webhook de Instagram informan de la actividad de una cuenta profesional en el momento en que ocurre: nuevos comentarios, @menciones y DMs. Meta envía cada uno como POST con JSON al endpoint HTTPS de la app conectada y reintenta una entrega fallida a ese endpoint durante hasta 36 horas. easyCoexistence reenvía cada evento a tu endpoint una sola vez, firmado por cuenta, sin reintentos. Con Instagram Login, las menciones llegan dentro de la notificación de comentarios.

36 hours

Cuánto tiempo sigue Meta reintentando una entrega fallida al endpoint de la app antes de descartarla.

1,000

La mayoría de las actualizaciones Meta las agrupa en una sola entrega webhook, aunque no garantiza el agrupamiento.

is_echo

El indicador que Meta pone en los eventos de mensaje enviados por la propia cuenta.

Public

Solo los medios de cuentas públicas disparan notificaciones de comentarios y menciones.

¿Qué eventos hay?

Para una cuenta profesional conectada con Instagram Login, tres tipos de actividad llegan como eventos:

  • Comentarios: un nuevo comentario en los medios de la cuenta, con el ID del comentario, su ID con alcance de Instagram y nombre de usuario, el texto, y el ID y tipo del medio.
  • Menciones: con Instagram Login llegan dentro de la notificación de comentarios y no como un campo propio.
  • Mensajes: un DM a la cuenta, con el remitente, el destinatario, una marca de tiempo y el mensaje en sí, incluidos texto, adjuntos y respuestas a historias.

¿Cómo llegan los eventos a tu endpoint?

Meta entrega los webhooks de Instagram a la app a la que se conectó la cuenta. easyCoexistence los recibe y reenvía cada uno al endpoint HTTPS que configuraste para esa cuenta, en cuanto llega, firmado con un secreto propio de esa cuenta.

Configura el endpoint con set_social_webhook_destination desde Claude o ChatGPT, o con la Partner API mediante PUT /channels/:id/webhook. El secreto de firma se muestra una sola vez; volver a configurar el endpoint emite uno nuevo, y pasar null como URL desactiva el reenvío.

¿Cómo es una entrega?

Un POST con cuerpo JSON que contiene la plataforma, el account_id que devuelve list_social_accounts para la conexión, el external_id de la cuenta de Instagram y entry: la entrada de webhook de Meta para el evento, sin cambios. Un DM llega igual, con un array messaging en lugar de changes. Un nuevo comentario se ve así:

A forwarded comment event
{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793318400,
    "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 una entrega?

Cada entrega lleva 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 de la petición, con la clave de firma de la cuenta. Calcúlalo sobre el cuerpo sin procesar tal como llegó, compara en tiempo constante y rechaza una marca de tiempo con más de 5 minutos de antigüedad.

Node.js: verifying X-EC-Signature
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: el reenvío pasa cada evento una sola vez, en memoria, y no guarda copia desde la que reintentar. Responde con un 2xx rápidamente y haz el trabajo después, y guarda lo que necesites en cuanto llegue, ya que Meta tampoco conserva un historial consultable de notificaciones pasadas.

Meta, por su parte, reintenta una entrega fallida a la app durante hasta 36 horas, así que el mismo evento puede llegarte dos veces de vez en cuando: deduplica por el ID del comentario o por el mid del mensaje.

¿Qué más debe revisar un manejador?

Algunos detalles de los payloads de Meta que hacen tropezar a un primer manejador:

  • is_echo: un evento de mensaje con is_echo en true lo envió la propia cuenta, así que no necesita respuesta.
  • Respuestas a historias: un DM que responde a una historia trae reply_to con el ID y la URL de la historia.
  • Menciones en historias: llegan como un mensaje cuyo tipo de adjunto es story_mention.
  • time: cuándo Meta envió la notificación, no cuándo se hizo el comentario o el mensaje; la marca de tiempo propia de un mensaje está en su entrada messaging.
  • IDs de álbum: los eventos de comentario no los incluyen; consulta el álbum con el ID del comentario.

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 tal como llegó.
  • Responder a los ecos. Un evento de mensaje con is_echo activo es uno que envió la cuenta, y responderle inicia un bucle.
  • Omitir la deduplicación. Meta puede volver a entregar el mismo evento tras un fallo, así que usa como clave el ID del comentario o el mid del mensaje.
Hacerlo con EasyCoexistence

easyCoexistence reenvía los comentarios, menciones y DMs de la cuenta de Instagram a tu endpoint HTTPS en cuanto llegan, firmados con un secreto de esa cuenta y sin copia guardada en el camino. Actívalo con set_social_webhook_destination desde Claude o ChatGPT, o con la Partner API. Desde US$ 9 hasta US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿Qué significa el campo time en un webhook de Instagram?

Cuándo Meta envió la notificación, no cuándo se hizo el comentario o el mensaje. La marca de tiempo propia de un DM está en su entrada messaging.

¿Meta reintenta las entregas fallidas de webhooks de Instagram?

Sí. Meta reintenta una entrega fallida a la app durante hasta 36 horas, así que el mismo evento puede llegar dos veces de vez en cuando: deduplica por el ID del comentario o por el mid del mensaje. easyCoexistence reenvía cada evento a tu endpoint una sola vez, así que responde con un 2xx rápidamente.

¿Cuántas actualizaciones puede contener una entrega de webhook de Instagram?

Hasta 1,000 cuando Meta las agrupa, aunque Meta no garantiza el agrupamiento. Recorre todo el array entry en lugar de leer solo su primer elemento.

¿Las menciones tienen evento propio?

No con Instagram Login. Meta incluye las menciones en la notificación de comentarios, así que llegan por el mismo camino que los comentarios.

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