Verificación de webhook de Facebook: hub.challenge y X-Hub-Signature-256
Facebook verifica un endpoint de webhook con un GET que trae hub.mode con el valor subscribe, hub.verify_token y hub.challenge; el endpoint compara el token con el configurado en el App Dashboard y devuelve el challenge como cuerpo. Después, cada evento llega como un POST firmado en X-Hub-Signature-256: sha256= seguido del HMAC-SHA256 del payload, con la clave del App Secret.
easyCoexistence gestiona el lado de Meta de cada Página que conectas: su app responde a hub.challenge, comprueba X-Hub-Signature-256 y suscribe la Página a feed, messages y mention, y luego reenvía los eventos a tu endpoint HTTPS firmados con X-EC-Signature y un secreto propio de esa Página.
El valor que hub.mode siempre trae en la petición de verificación de Meta; hub.challenge es un entero que hay que devolver.
Prefijo de X-Hub-Signature-256, seguido de la firma SHA256 que Meta genera a partir del payload y del App Secret.
Con qué rapidez un endpoint de webhook de Messenger debe responder con 200 OK a cada notificación.
Cuántas entregas fallidas hay antes de una alerta de Webhooks Disabled y de la desuscripción de la app de la Página.
Cuánto tiempo reintenta Meta una notificación fallida de Página, con frecuencia decreciente, antes de descartarla.
¿Qué contiene la petición de verificación de Meta?
Un GET a la URL de callback, enviado siempre que el producto Webhooks esté configurado en el App Dashboard o que se cree una suscripción mediante /{app-id}/subscriptions. Vienen tres parámetros de consulta:
- hub.mode: siempre subscribe.
- hub.challenge: un entero que el endpoint debe devolver.
- hub.
verify_token: la cadena introducida en el campo Verify Token del App Dashboard. - PHP convierte los puntos en guiones bajos, así que los lee como
hub_mode,hub_challengeyhub_verify_token.
¿Cómo debe responder el endpoint?
Con un 200 cuyo cuerpo completo es el valor de hub.challenge, pero solo cuando hub.mode es subscribe y hub.verify_token coincide; cualquier otra cosa recibe un 403, como en la app de ejemplo de Meta. El App Dashboard indica si el endpoint pasó la verificación, y /{app-id}/subscriptions responde con éxito o con un error. El endpoint necesita HTTPS con un certificado TLS o SSL válido, ya que no se admiten certificados autofirmados.
¿Cómo se calcula X-Hub-Signature-256?
Como un HMAC-SHA256 del payload de la petición, con la clave App Secret de la app, escrito en hexadecimal minúscula tras sha256=. La guía de Messenger de Meta añade que la firma cubre el payload con Unicode escapado, de modo que una cadena como äöå cuenta como \u00e4\u00f6\u00e5: calcula el hash del cuerpo crudo tal como llega, nunca de una copia decodificada o reserializada. Meta indica que validar es opcional, pero lo recomienda encarecidamente.
¿Cómo se comprueba en código?
Guarda los bytes crudos, calcula el HMAC, compara en tiempo constante y luego parsea. get_data de Flask devuelve el cuerpo sin tocar, que es sobre lo que se calculó la firma; parsearlo primero y volver a serializarlo cambiaría los bytes. Un endpoint pequeño que responde a la verificación y comprueba cada POST:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200¿Qué espera Meta después de la verificación?
Un 200 OK por cada notificación, en menos de 5 segundos para eventos de Messenger. Meta agrupa hasta 1,000 actualizaciones por entrega sin garantizarlo, y gestiona los fallos así:
- Notificaciones de Página: se reintentan de inmediato, luego algunas veces más con frecuencia decreciente durante 36 horas, y después se descartan.
- Notificaciones de Messenger: se reintentan algunas veces de inmediato; tras 15 minutos de fallos, llega una alerta a la cuenta de desarrollador.
- Tras una hora de fallos llega una alerta de Webhooks Disabled y la app se desuscribe de la Página hasta que vuelva a suscribirse.
- Los reintentos pueden entregar un evento dos veces y fuera de orden, así que deduplica y ordena los mensajes por su marca de tiempo.
- Las notificaciones pasadas no se pueden consultar después, así que guarda lo que necesites a medida que llega.
¿Cómo pasa easyCoexistence los controles de Meta?
Su app de Meta tiene una sola URL de callback para las Páginas que conecta, y ese endpoint hace ambas comprobaciones por sí mismo. Responde al GET solo cuando hub.mode es subscribe y el token de verificación coincide, comparado en tiempo constante, y devuelve 403 en otro caso; lee cada POST como texto crudo, recalcula X-Hub-Signature-256 con su App Secret, rechaza una discrepancia con 401 y responde a Meta de inmediato, procesando el evento después de la respuesta.
¿Cómo firma easyCoexistence lo que reenvía?
Con una firma propia, ya que la cabecera de Meta solo puede verificarse con el App Secret de easyCoexistence y no se transmite. Cada entrada de una Página conectada con un endpoint configurado se envía por POST allí como JSON, {platform, account_id, external_id, entry}, con una cabecera X-EC-Signature en la forma t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo crudo, con la clave del secreto de firma de esa Página:
- El secreto empieza por whsec_ y se muestra una sola vez, mediante
set_social_webhook_destinationo PUT /channels/:id/webhook en la Partner API. - Volver a configurar la URL emite un secreto nuevo, y una URL nula desactiva el reenvío.
- Cada reenvío se envía una vez, esperando hasta 8 segundos, sin seguir redirecciones, a una dirección HTTPS que resuelve a una IP pública.
- No se guarda copia del evento, así que no hay nada desde lo que reintentar.
¿Cómo se verifica X-EC-Signature?
Separa la cabecera en t y v1, rechaza una marca de tiempo de más de 5 minutos de antigüedad, recalcula el HMAC sobre t, un punto y el cuerpo crudo con el secreto de firma de la Página, y compara en tiempo constante. En Node.js, con el cuerpo guardado como bytes crudos:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});Errores comunes
- Envolver hub.challenge en JSON o comillas. El cuerpo del 200 tiene que ser el valor del challenge en sí.
- Calcular el HMAC después de un parser JSON. Parsear y volver a serializar cambia los bytes, y Meta firma el payload con Unicode escapado, así que calcula el hash del cuerpo crudo.
- Hacer el trabajo antes de responder. Messenger espera un 200 en 5 segundos, y una hora de fallos desuscribe la app de la Página.
- Comprobar la firma de Meta en eventos reenviados. Meta firma con el App Secret de easyCoexistence; un evento reenviado lleva X-EC-Signature, que se comprueba con el secreto de firma de la Página.
De US$ 9 a US$ 0.75 por conexión al mes, según añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿De dónde sale el verify token?
Lo eliges tú. Es la cadena que se introduce en el campo Verify Token al configurar los webhooks en el App Dashboard, o el verify_token que se envía a /{app-id}/subscriptions.
¿Puedo probar la verificación con curl?
Sí. La guía de Messenger de Meta envía un GET con hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED y hub.mode=subscribe, y un endpoint que funcione responde CHALLENGE_ACCEPTED.
¿Qué pasa si mi endpoint falla durante una hora?
Meta envía una alerta de Webhooks Disabled y desuscribe la app de la Página. Tras arreglar el endpoint, vuelve a suscribir la Página mediante subscribed_apps.
¿Necesito mi propia app de Meta para recibir los webhooks de una Página?
No con easyCoexistence. Meta entrega a su app, que reenvía los eventos de cada Página al endpoint que configuras, firmados con X-EC-Signature.
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