{"id":506,"date":"2026-10-28T16:04:39","date_gmt":"2026-10-28T16:04:39","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/validar-firma-webhook-whatsapp\/"},"modified":"2026-10-28T16:04:59","modified_gmt":"2026-10-28T16:04:59","slug":"validar-firma-webhook-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/validar-firma-webhook-whatsapp\/","title":{"rendered":"C\u00f3mo validar la firma del webhook de WhatsApp (X-Hub-Signature-256)"},"content":{"rendered":"\n

Actualizado el 28\/10\/2026<\/em><\/p>\n\n\n\n

Para validar la firma del webhook de WhatsApp, calcula un HMAC SHA-256 del cuerpo de la solicitud usando como clave el app secret<\/strong> (clave secreta) de tu app de Meta y comp\u00e1ralo con el encabezado X-Hub-Signature-256<\/code>, que llega con el formato sha256=<hash><\/code>. Si coinciden, el evento vino de Meta y no fue alterado en el camino. El error que m\u00e1s rompe la validaci\u00f3n es calcular el hash sobre el JSON que tu framework ya interpret\u00f3, y no sobre los bytes exactos que llegaron.<\/p>\n\n\n\n

Esta gu\u00eda muestra el paso a paso, c\u00f3digo listo para Node.js (Express), Python (FastAPI y Flask) y PHP, y los errores m\u00e1s comunes. Para el panorama general de la plataforma, consulta nuestra gu\u00eda de WhatsApp Cloud API<\/a>.<\/p>\n\n\n\n

Por qu\u00e9 validar la firma<\/h2>\n\n\n\n

La URL de tu webhook es p\u00fablica. Cualquiera que la descubra puede enviar un POST<\/code> con un JSON con el formato de Meta, simulando el mensaje de un cliente, un bot\u00f3n que confirma un pago o un estado delivered<\/code> que nunca ocurri\u00f3. Sin validaci\u00f3n, tu sistema acepta todo.<\/p>\n\n\n\n

La documentaci\u00f3n de webhooks de la Graph API<\/a> indica que Meta firma todas las notificaciones con SHA-256 y env\u00eda la firma en el encabezado X-Hub-Signature-256<\/code>, precedida de sha256=<\/code>. Validarla no es obligatorio, pero Meta lo recomienda. En la pr\u00e1ctica, es lo que separa un webhook confiable de un endpoint abierto.<\/p>\n\n\n\n

Las dos solicitudes que recibe tu endpoint<\/h2>\n\n\n\n

La misma URL recibe dos tipos de llamadas, cada una con su verificaci\u00f3n:<\/p>\n\n\n\n

Solicitud<\/th>Cu\u00e1ndo ocurre<\/th>Qu\u00e9 validar<\/th>Respuesta<\/th><\/tr><\/thead>
GET<\/code> de verificaci\u00f3n<\/td>Al configurar o cambiar la URL en el panel de la app<\/td>hub.mode<\/code> igual a subscribe<\/code> y hub.verify_token<\/code> igual al token que definiste<\/td>200<\/code> con el valor de hub.challenge<\/code><\/td><\/tr>
POST<\/code> de evento<\/td>Cada mensaje, estado o cambio en la cuenta<\/td>X-Hub-Signature-256<\/code> contra el HMAC del cuerpo sin procesar<\/td>200<\/code> r\u00e1pido; procesamiento en cola<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Seg\u00fan la p\u00e1gina Create a webhook endpoint<\/a>, si la verificaci\u00f3n es v\u00e1lida respondes 200<\/code> con el hub.challenge<\/code>; si no, respondes cualquier cosa distinta de 200<\/code> (un 403, por ejemplo). La misma p\u00e1gina exige un certificado TLS v\u00e1lido en el endpoint: no se aceptan certificados autofirmados.<\/p>\n\n\n\n

El verify token<\/em> y el app secret<\/em> son cosas distintas. El verify token es una cadena que t\u00fa inventas y registras en el panel; solo sirve para el GET<\/code>. El app secret lo genera Meta, est\u00e1 en Configuraci\u00f3n de la app > B\u00e1sica<\/strong> y es el que firma los POST<\/code>.<\/p>\n\n\n\n

Paso a paso de la validaci\u00f3n<\/h2>\n\n\n\n
    \n
  1. Lee el cuerpo de la solicitud como bytes<\/strong>, antes de cualquier parser de JSON.<\/li>\n\n\n
  2. Calcula HMAC-SHA256(clave = app secret, mensaje = cuerpo sin procesar)<\/code> y convi\u00e9rtelo a hexadecimal.<\/li>\n\n\n
  3. Arma sha256=<\/code> + hash y comp\u00e1ralo con el encabezado X-Hub-Signature-256<\/code> usando una comparaci\u00f3n de tiempo constante.<\/li>\n\n\n
  4. Si no coincide, responde 401 o 403 y descarta el evento.<\/li>\n\n\n
  5. Si coincide, interpreta el JSON, pon el evento en una cola y responde 200<\/code>.<\/li>\n\n<\/ol>\n\n\n\n

    La comparaci\u00f3n de tiempo constante (crypto.timingSafeEqual<\/code>, hmac.compare_digest<\/code>, hash_equals<\/code>) evita que un atacante adivine el hash byte por byte midiendo el tiempo de respuesta.<\/p>\n\n\n\n

    Ejemplo en Node.js con Express<\/h2>\n\n\n\n

    La clave es usar express.raw()<\/code> en la ruta del webhook, para que req.body<\/code> sea un Buffer<\/code> con los bytes originales:<\/p>\n\n\n\n

    import express from 'express';\nimport crypto from 'node:crypto';\n\nconst app = express();\nconst APP_SECRET = process.env.META_APP_SECRET;\nconst VERIFY_TOKEN = process.env.WEBHOOK_VERIFY_TOKEN;\n\n\/\/ GET de verificaci\u00f3n\napp.get('\/webhook', (req, res) => {\n  const mode = req.query['hub.mode'];\n  const token = req.query['hub.verify_token'];\n  const challenge = req.query['hub.challenge'];\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) {\n    return res.status(200).send(challenge);\n  }\n  return res.sendStatus(403);\n});\n\n\/\/ POST de eventos: cuerpo sin procesar solo en esta ruta\napp.post('\/webhook', express.raw({ type: 'application\/json' }), (req, res) => {\n  const recibida = req.get('X-Hub-Signature-256') || '';\n  const esperada = 'sha256=' + crypto\n    .createHmac('sha256', APP_SECRET)\n    .update(req.body)\n    .digest('hex');\n\n  const a = Buffer.from(recibida);\n  const b = Buffer.from(esperada);\n  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {\n    return res.sendStatus(401);\n  }\n\n  const evento = JSON.parse(req.body.toString('utf8'));\n  res.sendStatus(200);\n  colaDeEventos.push(evento); \/\/ procesa fuera del ciclo de la solicitud\n});\n\napp.use(express.json()); \/\/ las dem\u00e1s rutas pueden usar JSON normalmente\napp.listen(3000);<\/code><\/pre>\n\n\n\n
    Si tu app ya declara app.use(express.json())<\/code> antes de esta ruta, el cuerpo llega interpretado y el hash no coincide. Hay dos salidas: declarar la ruta del webhook antes del middleware global o guardar los bytes en el propio express.json<\/code>:<\/p>\n\n\n\n
    app.use(express.json({\n  verify: (req, _res, buf) => { req.rawBody = buf; },\n}));\n\/\/ luego usa req.rawBody en createHmac<\/code><\/pre>\n\n\n\n
    Ejemplo en Python con FastAPI<\/h2>\n\n\n\n
    En FastAPI, await request.body()<\/code> devuelve los bytes exactos. No firmes el modelo Pydantic del cuerpo:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport json\nimport os\n\nfrom fastapi import FastAPI, HTTPException, Request, Response\n\napp = FastAPI()\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\nVERIFY_TOKEN = os.environ[\"WEBHOOK_VERIFY_TOKEN\"]\n\n\n@app.get(\"\/webhook\")\nasync def verificar(request: Request):\n    p = request.query_params\n    if p.get(\"hub.mode\") == \"subscribe\" and p.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return Response(content=p.get(\"hub.challenge\", \"\"), media_type=\"text\/plain\")\n    raise HTTPException(status_code=403)\n\n\n@app.post(\"\/webhook\")\nasync def recibir(request: Request):\n    cuerpo = await request.body()\n    recibida = request.headers.get(\"x-hub-signature-256\", \"\")\n    esperada = \"sha256=\" + hmac.new(APP_SECRET, cuerpo, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(recibida, esperada):\n        raise HTTPException(status_code=401)\n\n    evento = json.loads(cuerpo)\n    # encola el evento y responde r\u00e1pido\n    return {\"ok\": True}<\/code><\/pre>\n\n\n\n
    Ejemplo en Python con Flask<\/h2>\n\n\n\n
    En Flask, usa request.get_data()<\/code>, que devuelve el cuerpo sin procesar:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport os\n\nfrom flask import Flask, abort, request\n\napp = Flask(__name__)\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\n\n\n@app.post(\"\/webhook\")\ndef recibir():\n    cuerpo = request.get_data()\n    recibida = request.headers.get(\"X-Hub-Signature-256\", \"\")\n    esperada = \"sha256=\" + hmac.new(APP_SECRET, cuerpo, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(recibida, esperada):\n        abort(401)\n    evento = request.get_json()\n    return \"\", 200<\/code><\/pre>\n\n\n\n
    Ejemplo en PHP<\/h2>\n\n\n\n
    En PHP, el cuerpo sin procesar viene de php:\/\/input<\/code>. Cuidado con el GET<\/code>: PHP reemplaza los puntos por guiones bajos en los nombres de par\u00e1metros, as\u00ed que hub.verify_token<\/code> se convierte en $_GET['hub_verify_token']<\/code>.<\/p>\n\n\n\n
    <?php\n$appSecret = getenv('META_APP_SECRET');\n$verifyToken = getenv('WEBHOOK_VERIFY_TOKEN');\n\nif ($_SERVER['REQUEST_METHOD'] === 'GET') {\n    if (($_GET['hub_mode'] ?? '') === 'subscribe'\n        && hash_equals($verifyToken, $_GET['hub_verify_token'] ?? '')) {\n        echo $_GET['hub_challenge'] ?? '';\n        exit;\n    }\n    http_response_code(403);\n    exit;\n}\n\n$cuerpo = file_get_contents('php:\/\/input');\n$recibida = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';\n$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $appSecret);\n\nif (!hash_equals($esperada, $recibida)) {\n    http_response_code(401);\n    exit;\n}\n\n$evento = json_decode($cuerpo, true);\nhttp_response_code(200);<\/code><\/pre>\n\n\n\n
    Errores comunes que hacen que la firma no coincida<\/h2>\n\n\n\n
    Hash calculado sobre el JSON interpretado.<\/strong> Es el error n\u00famero uno. JSON.stringify(req.body)<\/code> o json.dumps(payload)<\/code> generan un texto distinto del original: cambian espacios, orden de claves y escape de caracteres. Un solo byte distinto cambia todo el hash. Firma siempre los bytes que llegaron.<\/p>\n\n\n\n
    Codificaci\u00f3n equivocada.<\/strong> Convertir el cuerpo a texto con un charset incorrecto (latin-1 en vez de UTF-8, por ejemplo) altera nombres con tilde y emojis. Trabaja con bytes hasta terminar la validaci\u00f3n.<\/p>\n\n\n\n
    Secret equivocado.<\/strong> El valor correcto es el app secret de la app suscrita al webhook. No es el token de acceso, ni el verify token, ni el secret de otra app del mismo portafolio. Si tienes apps separadas para pruebas y producci\u00f3n, cada entorno necesita el suyo.<\/p>\n\n\n\n
    Prefijo ignorado.<\/strong> El encabezado trae sha256=<\/code> antes del hash. O comparas la cadena completa (como en los ejemplos) o quitas el prefijo de ambos lados.<\/p>\n\n\n\n
    Middleware o gateway que altera el cuerpo.<\/strong> Proxies, gateways de API y funciones serverless a veces reformatean o codifican el cuerpo antes de entregarlo a tu c\u00f3digo. Si la validaci\u00f3n falla solo en producci\u00f3n, registra el tama\u00f1o del cuerpo recibido y comp\u00e1ralo con el Content-Length<\/code>.<\/p>\n\n\n\n
    Secret cambiado sin actualizar el servidor.<\/strong> Al restablecer el app secret en el panel, los eventos pasan a llegar firmados con el nuevo valor. Si tu servidor rechaza todo con 401, Meta reintenta: seg\u00fan la descripci\u00f3n general de webhooks<\/a>, las entregas que no reciben 200<\/code> se repiten con frecuencia decreciente durante hasta 7 d\u00edas, lo que puede generar eventos duplicados. Monitorea la tasa de 401 del endpoint para detectarlo a tiempo.<\/p>\n\n\n\n
    Buenas pr\u00e1cticas despu\u00e9s de validar<\/h2>\n\n\n\n