Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Verificación de webhooks de Instagram: hub.challenge y X-Hub-Signature-256

Configurar webhooks de Instagram requiere un endpoint HTTPS que responda a la verificación GET de Meta, que trae hub.mode con el valor subscribe, hub.verify_token y hub.challenge, comprobando el token y devolviendo el valor de hub.challenge. Después, Meta envía eventos JSON firmados en X-Hub-Signature-256 con el secret de la app, una vez que la app se suscribe a los campos y cada cuenta se suscribe mediante su edge subscribed_apps.

easyCoexistence se encarga del lado de Meta: su app pasa la verificación, comprueba X-Hub-Signature-256, suscribe cada cuenta de Instagram conectada a comentarios, mensajes y menciones, y reenvía los eventos a tu endpoint HTTPS firmados con X-EC-Signature y un secret por cuenta, vigilando cada conexión las 24 horas del día.

subscribe

El valor hub.mode siempre viaja en la petición de verificación de Meta.

36 hours

Periodo durante el cual Meta reintenta una notificación fallida, con frecuencia decreciente, antes de descartarla.

15 minutes

Número de entregas de mensajería fallidas antes de que Meta envíe una alerta a la cuenta de desarrollador.

1 hour

Número de entregas de mensajería fallidas antes de una alerta Webhooks Disabled y de la desuscripción de la app de la cuenta.

Live

Modo de app que Meta exige antes de que una app reciba notificaciones de las cuentas de sus usuarios.

¿Cómo funciona la configuración de webhooks de Instagram?

En cuatro pasos, en el orden que da la guía de Meta. El endpoint debe pasar la verificación antes de que se pueda seleccionar cualquier campo, la app debe estar en modo Live para recibir notificaciones de las cuentas de sus usuarios, y la verificación de negocio es obligatoria para el acceso de producción.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

¿Qué contiene la petición de verificación?

Un GET a la URL de callback, enviado siempre que el producto Webhooks esté configurado en el App Dashboard. Cuando hub.verify_token coincide con el token propio del endpoint, la respuesta es un 200 con el valor de hub.challenge como cuerpo completo; de lo contrario, un 403. El dashboard indica si el endpoint pasó la verificación.

  • hub.mode: siempre subscribe.
  • hub.challenge: un entero que genera Meta, que el endpoint debe devolver.
  • hub.verify_token: la cadena introducida en el campo Verify Token del dashboard, que solo deben conocer Meta y el endpoint.
  • En PHP, los puntos de estos nombres se convierten en guiones bajos, así que los valores llegan como hub_mode, hub_challenge y hub_verify_token.
The verification request and its answer
GET https://<YOUR_HOST>/webhooks/instagram
  ?hub.mode=subscribe
  &hub.challenge=1158201444
  &hub.verify_token=<YOUR_VERIFY_TOKEN>

HTTP/1.1 200 OK
Content-Type: text/plain

1158201444

¿Dónde se configuran el callback y los campos?

En el App Dashboard, en Instagram, API setup with Instagram login, Configure webhooks: la URL de callback y el verify token se introducen ahí, y al guardarlos se dispara la petición de verificación. El producto Instagram empieza suscrito a comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral y messaging_seen, y Manage permite desuscribirse de cualquiera de ellos. El botón Test envía una notificación de ejemplo para el campo seleccionado.

¿Cómo se verifica X-Hub-Signature-256?

Meta firma cada notificación de evento con un HMAC-SHA256 del payload, con la clave del secret de la app, y la envía en X-Hub-Signature-256 como sha256= seguido del digest hexadecimal. El receptor calcula el mismo HMAC sobre el cuerpo crudo de la petición y lo compara con la cabecera, en tiempo constante. La guía de mensajería de Meta indica que la firma cubre el payload con Unicode escapado, así que hashear el JSON decodificado o reserializado da un resultado distinto.

Node.js: answering verification and checking X-Hub-Signature-256
import crypto from "node:crypto";
import express from "express";

const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;

// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
  const ok = req.query["hub.mode"] === "subscribe" &&
    req.query["hub.verify_token"] === VERIFY_TOKEN;
  if (!ok) return res.sendStatus(403);
  res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});

// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
  const expected = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
  );
  const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // answer first, work after
  const body = JSON.parse(req.body.toString("utf8"));
  // hand body.entry to a queue or background job
});

app.listen(3000);

¿Por qué solo el secret de la app puede comprobarla?

Porque la firma es un HMAC con clave de ese secret. Sin él, nadie puede calcular el valor esperado, y nadie que tenga una copia de un payload puede falsificarlo; por eso la comprobación pertenece al servidor que recibe las peticiones de Meta para la app. Meta pide que los app secrets, los access tokens y las credenciales de cliente no aparezcan en logs ni en consultas de soporte. Un sistema que recibe eventos reenviados por otra app no puede comprobar la firma de Meta, y depende en su lugar de la firma propia de esa app.

¿Por qué cada cuenta necesita su propia suscripción?

Porque el App Dashboard define lo que la app puede recibir, y las notificaciones de una cuenta solo empiezan cuando esa cuenta también está suscrita. Con Instagram Login, envía POST /<IG_ID>/subscribed_apps a graph.instagram.com con el token de acceso de usuario de Instagram de la cuenta y subscribed_fields con la lista de campos seleccionados para la app, separados por comas. Una llamada correcta devuelve success con valor true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

¿Qué hace Meta cuando fallan las entregas?

Reintenta y luego desiste. La guía de Meta pide un 200 OK para cada notificación y advierte de que el envío por lotes, de hasta 1,000 actualizaciones, no está garantizado. Una actualización fallida se reintenta de inmediato, después algunas veces más con frecuencia decreciente durante 36 hours, y se descarta después; por eso el mismo evento puede llegar dos veces. Los eventos de mensajería siguen las reglas de entrega de mensajería de Meta, que actúan más rápido:

  • Se espera un 200 OK en 5 seconds, y una entrega fallida recibe algunos reintentos inmediatos, así que deduplica por el mid del mensaje.
  • Tras 15 minutes de fallos, se envía una alerta a la cuenta de desarrollador.
  • Tras una hora de fallos, llega una alerta Webhooks Disabled y la app se desuscribe de los webhooks de la cuenta hasta que vuelva a suscribirse.
  • Los mensajes enviados durante una caída pueden llegar desordenados, así que ordénalos por timestamp.

¿Qué debes revisar cuando no llega nada?

La lista de comprobación de resolución de problemas de Meta, que cubre la mayoría de endpoints silenciosos, en este orden:

  • La URL de callback pasó su comprobación y es accesible por HTTPS con un certificado válido; no se admiten certificados autofirmados.
  • La app seleccionó el campo y tiene el nivel de acceso que necesita, Advanced Access para comments y live_comments.
  • Las notificaciones están activadas para la cuenta mediante subscribed_apps, con un token del mismo login.
  • La cuenta cumple las reglas del campo: las notificaciones de comentarios requieren contenido de una cuenta pública.
  • El servidor responde con success antes de iniciar tareas lentas.

¿Por qué easyCoexistence vuelve a firmar los eventos reenviados?

Porque la firma de Meta no puede viajar. La app de easyCoexistence recibe la entrega de Meta, comprueba X-Hub-Signature-256 con su propio secret de app, responde a Meta de inmediato, y envía por POST cada entrada de una cuenta conectada al endpoint configurado para esa cuenta, dentro de un nuevo cuerpo con platform, account_id, external_id y entry. La cabecera de Meta no se reenvía y no podría comprobarse sin ese secret, así que cada reenvío lleva Content-Type: application/json y X-EC-Signature, firmado con un secret que pertenece a esa sola cuenta.

¿Cómo se verifica X-EC-Signature?

La cabecera tiene el formato t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto y el cuerpo crudo, con la clave del secret de firma de la cuenta. Vuelve a calcularlo sobre los bytes exactamente como llegaron, compara en tiempo constante y rechaza una marca de tiempo de más de 5 minutes de antigüedad.

  • El secret empieza por whsec_ y se muestra una sola vez, con set_social_webhook_destination o PUT /channels/:id/webhook al configurar la URL.
  • Volver a configurar la URL emite un nuevo secret, y una URL nula desactiva el reenvío.
  • Cada evento se envía una vez, esperando hasta 8 seconds, sin seguir redirecciones, a una dirección HTTPS que resuelva a una IP pública.
  • Al eliminar la conexión, la cuenta se desuscribe de los webhooks de Meta y se borran su endpoint y su secret.
Python: checking X-EC-Signature
import hashlib, hmac, time

def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """Check X-EC-Signature on an event forwarded by easyCoexistence."""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False  # missing, malformed or older than 5 minutes
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())

Errores comunes

  • Devolver el challenge como JSON o entre comillas. Meta espera el valor de hub.challenge tal cual como cuerpo, con estado 200.
  • Hashear un cuerpo ya parseado. Un parser de JSON descarta los bytes exactos que Meta firmó, así que guarda el cuerpo crudo para el HMAC y parséalo después.
  • Suscribir la app y olvidar la cuenta. Hasta que POST /<IG_ID>/subscribed_apps funcione para una cuenta, no llega ninguna notificación de ella.
  • Dejar fallar un endpoint durante una hora. Meta desactiva los webhooks de mensajería y desuscribe la app de la cuenta, que entonces hay que volver a suscribir.
Hacerlo con EasyCoexistence

Actívalo con set_social_webhook_destination o con la Partner API. De US$ 9 a US$ 0.75 por conexión al mes, con descenso a medida que sumas conexiones, y los primeros 3 días gratis.

Preguntas frecuentes

¿Qué es hub.challenge en los webhooks de Instagram?

Un entero que Meta envía en su GET de verificación. Tras comprobar hub.verify_token, el endpoint lo devuelve como cuerpo de la respuesta, lo que demuestra que controla la URL.

¿Por qué faltan hub.mode y hub.challenge en PHP?

PHP convierte los puntos de los nombres de parámetros en guiones bajos, así que los valores de verificación de Meta llegan como hub_mode, hub_challenge y hub_verify_token.

¿Cómo vuelvo a activar los webhooks de Instagram después de que Meta los desactive?

Corrige el endpoint y luego vuelve a suscribir la cuenta con POST /<IG_ID>/subscribed_apps y los mismos campos.

¿Funciona un certificado autofirmado en un endpoint de webhook de Instagram?

No, Meta no admite certificados autofirmados: la URL de callback debe ser accesible por HTTPS con un certificado válido, el primer punto de la lista de comprobación de Meta.

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