Saltar al contenido

Cualquiera puede mandarte un webhook falso: verifica el HMAC de Shopify

En la práctica/ 15 min de lectura

Shopify firma cada webhook con un HMAC del cuerpo crudo. Si no lo compruebas, cualquiera que encuentre tu URL puede inventarse un pedido. Código Node probado.

  • Shopify
  • Apps de Shopify
  • Node.js
  • Seguridad
En este artículo (8)
  1. Por qué un webhook sin verificar es un riesgo
  2. Cómo firma Shopify (HMAC SHA256 del cuerpo, en base64)
  3. Verificación en Node con el cuerpo crudo
  4. Comparación segura contra ataques de tiempo
  5. Qué responder si la firma no coincide
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Para verificar un webhook de Shopify, calcula el HMAC-SHA256 del cuerpo crudo de la petición con el client secret de tu app, pásalo a base64 y compáralo en tiempo constante con el encabezado X-Shopify-Hmac-Sha256. Si coincide, encola el trabajo y responde 200. Si no coincide o no viene, responde 401 y no proceses nada.

Aquí vas a ver qué firma Shopify exactamente, por qué el cuerpo tiene que llegar intacto a tu función, cómo hacerlo en Express y en un route handler de Next.js, y qué responder en cada caso. Todo el código lo ejecutamos en Node 22, con pruebas que mandan peticiones firmadas de verdad con un secreto de prueba.

Por qué un webhook sin verificar es un riesgo

Un endpoint de webhooks es una URL pública que acepta POST de cualquiera. Shopify la llama cuando pasa algo en la tienda, pero nada impide que otra persona mande a la misma URL un JSON con la misma forma. Si tu código confía en lo que llega, ese JSON inventado puede crear un pedido que nunca existió y disparar su envío, borrar datos con un customers/redact falso o llenar tu cola de basura.

Esconder la URL no sirve: aparece en la configuración de la app y en los logs. CORS tampoco, porque solo lo aplican los navegadores, como explicamos en por qué CORS no protege tu API. Lo que distingue un envío de Shopify de uno falso es la firma, y Shopify lo pide sin rodeos en cómo verificar las entregas de webhooks: verifica la firma antes de procesar y rechaza cualquier entrega cuya firma no coincida.

Cómo firma Shopify (HMAC SHA256 del cuerpo, en base64)

Cada entrega por HTTPS lleva en el encabezado X-Shopify-Hmac-Sha256 una firma HMAC-SHA256 en base64, generada con el client secret de tu app y el cuerpo crudo de la petición. Un HMAC mezcla un secreto con un mensaje: sin el secreto no puedes producir la firma correcta, y si cambia un solo byte del mensaje, la firma cambia por completo. Tú tienes el mismo secreto, así que calculas la firma por tu cuenta y la comparas con la que llegó.

El secreto es el client secret del Dev Dashboard, en Apps → tu app → Settings → Credentials, no el token de acceso de la Admin API. La guía de credenciales de Shopify pide tratarlo como una contraseña y no ponerlo nunca en código que llegue al navegador. La firma solo existe en las entregas por HTTPS: las de Google Cloud Pub/Sub y Amazon EventBridge no la necesitan.

Junto con la firma llegan otros encabezados. Estos son los que lista la estructura de entrega de webhooks:

EncabezadoQué contienePara qué te sirve
X-Shopify-Hmac-Sha256La firma HMAC en base64; solo en HTTPSComprobar que la entrega viene de Shopify
X-Shopify-TopicEl tema, por ejemplo products/updateDecidir qué trabajo encolar
X-Shopify-Shop-DomainEl dominio myshopify.com de la tiendaSaber de qué tienda es
X-Shopify-API-VersionLa versión de la API con la que se armó el cuerpoInterpretar los campos
X-Shopify-Webhook-IdUna clave única por entregaDetectar duplicados
X-Shopify-Event-IdUn id que comparten todas las entregas de una misma acción del comercianteRelacionar entregas de varias suscripciones
X-Shopify-Triggered-AtCuándo disparó Shopify la entregaRegistrar y ordenar
X-Shopify-Name (opcional)El nombre que le diste a la suscripciónDistinguir suscripciones

Shopify pide leer estos nombres sin distinguir mayúsculas, porque HTTP/2 suele pasarlos a minúsculas. Por eso en el código vas a ver x-shopify-hmac-sha256.

cómo se verifica un webhook de ShopifyShopify firma cada envíoX-Shopify-Hmac-Sha256 = base64(HMAC-SHA256(client secret, cuerpo crudo))POST por HTTPS a tu endpoint1 lee el cuerpo crudoexpress.raw() o arrayBuffer()2 calcula tu propio HMACHMAC-SHA256, client secret, base643 compara en tiempo constantemismo largo + timingSafeEqualcoincideX-Shopify-Webhook-Id ya visto: 200nuevo: encola y 200 en menos de 5 sno coincide o falta401 Unauthorized, nada procesadosin firma válida, el cuerpo no se tocaShopify espera un 200 en 5 s; si no llega, reintenta 8 veces en 4 horas

Desliza la figura para verla completa

Verificación en Node con el cuerpo crudo

La regla que más se rompe: la firma se calcula sobre los bytes exactos que llegaron, no sobre el objeto que obtienes al parsearlos. Si un middleware como express.json() ya convirtió el cuerpo en objeto, volver a armarlo con JSON.stringify no te devuelve los mismos bytes. En nuestra prueba, el cuerpo perdió tres espacios y el id, que pasa de Number.MAX_SAFE_INTEGER, se redondeó. Resultado: otra firma.

el mismo JSON, otros bytes, otro HMAClo que llegó: el cuerpo crudo{"id": 820982911946154508, "email": "jon@example.com"}54 bytes · SxC0VGL6QEViUkUL42BJevF1PyxQ1J7zIzFu77aieIs=JSON.stringify(JSON.parse(body))lo que reconstruye tu código{"id":820982911946154500,"email":"jon@example.com"}51 bytes · OVKTpO1rdZWUzfBQ19+QbZVS0hFMn4o7uI9wzlu4arw=· sin los espacios: 3 bytes menos· el id supera Number.MAX_SAFE_INTEGER y JavaScript lo redondeaverifica los bytes que llegaron, no el objetoejemplo ilustrativo, firmado con el secreto de prueba test_secret_do_not_use

Desliza la figura para verla completa

Esta es la función de verificación, verify.mjs, sin dependencias:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyShopifyWebhook(rawBody, hmacHeader, secret) {
  if (!secret || typeof hmacHeader !== "string") return false;
  if (typeof rawBody !== "string" && !Buffer.isBuffer(rawBody)) return false;

  const expected = Buffer.from(createHmac("sha256", secret).update(rawBody).digest("base64"));
  const received = Buffer.from(hmacHeader);

  return expected.length === received.length && timingSafeEqual(expected, received);
}
  1. Sin secreto, o sin encabezado, devuelve false. Lo primero importa más de lo que parece: si la variable de entorno queda vacía y calculas el HMAC con una clave vacía, cualquiera puede firmar con esa misma clave vacía.
  2. Si el cuerpo no es un Buffer ni un string, devuelve false. Es lo que tienes en req.body cuando express.raw() no procesó la petición (Express deja undefined) o cuando express.json() llegó antes (un objeto).
  3. expected es tu firma: HMAC-SHA256 del cuerpo crudo con el client secret, en base64, como la de Shopify.
  4. received es el encabezado tal como llegó, en bytes.
  5. Compara primero el largo y después los bytes, con timingSafeEqual. Ese orden importa, y lo vemos en la siguiente sección.

Con Express

En Express 5, express.raw() deja el cuerpo como Buffer en req.body, pero solo en las peticiones cuyo Content-Type coincide con su opción type (por defecto, application/octet-stream), según la referencia de Express. Por eso va solo en la ruta del webhook, con type: "application/json". Este es server.mjs:

import express from "express";
import { verifyShopifyWebhook } from "./verify.mjs";
import { enqueueWebhook } from "./webhook-queue.mjs";

const secrets = [process.env.SHOPIFY_API_SECRET, process.env.SHOPIFY_API_SECRET_OLD].filter(Boolean);

export const app = express();

app.post("/webhooks/shopify", express.raw({ type: "application/json" }), async (req, res) => {
  const hmac = req.get("x-shopify-hmac-sha256");
  if (!secrets.some((secret) => verifyShopifyWebhook(req.body, hmac, secret))) {
    return res.status(401).send("invalid hmac");
  }

  await enqueueWebhook({
    id: req.get("x-shopify-webhook-id"),
    topic: req.get("x-shopify-topic"),
    shop: req.get("x-shopify-shop-domain"),
    body: req.body.toString("utf8"),
  });
  res.sendStatus(200);
});

app.use(express.json());
  1. secrets junta el secreto actual y, mientras rotas, el anterior. filter(Boolean) quita los que no están definidos: sin ninguno, toda entrega recibe 401.
  2. express.raw() va solo en esta ruta, así que aquí req.body es el Buffer original. req.get() lee encabezados sin distinguir mayúsculas.
  3. Si ningún secreto valida la firma, responde 401 y sale sin tocar el cuerpo.
  4. enqueueWebhook guarda el id de la entrega, el tema, la tienda y el cuerpo. Si falla, Express 5 pasa la promesa rechazada a su manejador de errores, Shopify recibe un 500 y reintenta. Si no, res.sendStatus(200) confirma la entrega.
  5. app.use(express.json()) va después de la ruta del webhook: el resto de tu API sigue recibiendo JSON parseado.

Con un route handler de Next.js

En el App Router, un route handler recibe un Request estándar de la Web. La documentación de route handlers trae un ejemplo de webhook que lee el cuerpo con request.text() y aclara que, a diferencia de las API Routes del Pages Router, no hace falta configurar bodyParser. Guarda la función de arriba como lib/verify-shopify-webhook.js, la cola como lib/webhook-queue.js, y crea app/api/webhooks/shopify/route.js:

import { verifyShopifyWebhook } from "@/lib/verify-shopify-webhook";
import { enqueueWebhook } from "@/lib/webhook-queue";

const secrets = [process.env.SHOPIFY_API_SECRET, process.env.SHOPIFY_API_SECRET_OLD].filter(Boolean);

export async function POST(request) {
  const rawBody = Buffer.from(await request.arrayBuffer());
  const hmac = request.headers.get("x-shopify-hmac-sha256");
  if (!secrets.some((secret) => verifyShopifyWebhook(rawBody, hmac, secret))) {
    return new Response("invalid hmac", { status: 401 });
  }

  await enqueueWebhook({
    id: request.headers.get("x-shopify-webhook-id"),
    topic: request.headers.get("x-shopify-topic"),
    shop: request.headers.get("x-shopify-shop-domain"),
    body: rawBody.toString("utf8"),
  });
  return new Response(null, { status: 200 });
}
  1. Los dos import usan el alias @/ de Next.js; si tu proyecto no lo tiene, usa la ruta relativa.
  2. Buffer.from(await request.arrayBuffer()) lee el cuerpo una sola vez, como bytes. No llames antes a request.json(): consume el cuerpo y te deja solo el objeto.
  3. Con firma inválida o ausente, 401. Lo demás es igual que en Express: encolar y responder 200.

Con JSON en UTF-8 válido, request.text() también funciona; con un byte inválido, text() lo reemplaza y la firma deja de coincidir (lo probamos), así que preferimos los bytes. Buffer y node:crypto están en el runtime nodejs, el predeterminado según la configuración de segmentos de Next.js.

Si prefieres una librería: con la plantilla de Shopify para React Router, authenticate.webhook(request) verifica la firma antes de que corra tu código, y @shopify/shopify-api trae shopify.webhooks.validate(), que recibe el cuerpo crudo como string. No la instalamos para este artículo.

Comparación segura contra ataques de tiempo

Comparar dos strings con === puede terminar en el primer carácter distinto. En teoría, alguien que mide cuánto tarda tu respuesta podría ir adivinando la firma carácter por carácter. No hace falta decidir si ese ataque es práctico en tu caso, porque evitarlo cuesta una línea: según la documentación de crypto de Node, timingSafeEqual compara los bytes con un algoritmo de tiempo constante, no filtra información de tiempo que permita adivinar uno de los valores y sirve para comparar resúmenes HMAC.

La misma documentación avisa de dos cosas. La primera: timingSafeEqual lanza un error si los dos buffers no miden lo mismo. Este es length.mjs:

import { timingSafeEqual } from "node:crypto";

try {
  timingSafeEqual(Buffer.from("SxC0VGL6QEViUkUL42BJevF1PyxQ1J7zIzFu77aieIs="), Buffer.from("abc"));
} catch (err) {
  console.log(err.name, err.code);
  console.log(err.message);
}

Y esta, su salida:

RangeError ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH
Input buffers must have the same byte length
  1. El primer buffer es una firma real de 44 caracteres; el segundo, un encabezado de tres.
  2. timingSafeEqual no devuelve false: lanza un RangeError con el código ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH.
  3. Dentro de una ruta de Express, una excepción así sin capturar se vuelve un 500 en lugar de un 401.

Comparar el largo primero no revela nada útil: una firma HMAC-SHA256 en base64 siempre mide 44 caracteres (32 bytes). La segunda advertencia es que timingSafeEqual no vuelve seguro el código que la rodea; por eso nuestra función solo sale antes de tiempo cuando falta algo o el largo no coincide, nunca según el contenido de la firma.

El ejemplo manual de la documentación de Shopify pasa la firma decodificada directo a timingSafeEqual, sin revisar el largo. Lo ejecutamos tal cual en Express 5.3.0 y no arrancó: app.post('*', ...) falla con TypeError: Missing parameter name at index 1: *, porque Express 5 ya no acepta un comodín sin nombre. Con la ruta cambiada a '/*splat' respondió 200 y 401 como debe, pero 500 cuando faltaba el encabezado o tenía otro largo. Ese 500 no deja pasar a nadie, pero no es la respuesta que pide la App Store.

Qué responder si la firma no coincide

Con firma inválida o ausente, responde 401 Unauthorized y no proceses nada: ni base de datos, ni cola, ni logs con el cuerpo completo. Es lo que hace el ejemplo manual de Shopify, y en las apps de la App Store es obligatorio para los webhooks de cumplimiento: la página de cumplimiento de leyes de privacidad dice que, si uno de ellos llega con un HMAC inválido, la app debe devolver 401 Unauthorized. Son customers/data_request, customers/redact y shop/redact, y la app tiene que estar suscrita a los tres y verificarlos antes de mandarla a revisión. Ojo: el ejemplo de la librería responde 400, no 401.

Con firma válida, responde rápido. Según la documentación de Shopify, cualquier respuesta fuera del rango 200, incluidas las 3XX, cuenta como error; la conexión tiene un segundo de tiempo máximo y la petición completa, cinco. Si no recibe respuesta o recibe un error, Shopify reintenta 8 veces durante las siguientes 4 horas. Tras 8 fallos seguidos, borra la suscripción si la creaste con la Admin API, y manda avisos al correo de emergencia de la app.

qué responder a cada webhookllegarespondesy luegofirma válida, id nuevo200lo procesa la cola, despuésfirma válida, id ya visto200no lo proceses otra vezfirma inválida o ausente401no toques nadatu cola falla al encolar500Shopify reintentamás de 5 s sin respondertimeoutcuenta como fallo8 fallos seguidos—se borra la suscripción (Admin API)un 200 solo después de verificar y encolar8 reintentos en 4 horas; un 3XX también cuenta como error

Desliza la figura para verla completa

Responder rápido significa no hacer el trabajo dentro de la petición: verificar, encolar y responder. Shopify sugiere justo eso, junto con un proceso de conciliación que recupere de vez en cuando lo que se haya perdido. La cola de nuestro ejemplo es lo mínimo para probar, webhook-queue.mjs:

// shortcut: in memory and in one process; in production, a table with the webhook id as its primary key.
const seen = new Set();
export const jobs = [];

export async function enqueueWebhook(job) {
  if (seen.has(job.id)) return false;
  seen.add(job.id);
  jobs.push(job);
  return true;
}
  1. El comentario lo dice: vive en memoria y en un solo proceso. En producción, una tabla con el id de la entrega como clave primaria.
  2. seen guarda los X-Shopify-Webhook-Id ya recibidos: Shopify avisa que la misma entrega puede llegar más de una vez, por ejemplo tras un timeout o un reintento.
  3. Si el id ya está, no encola nada y el endpoint responde 200 igual, como pide Shopify. Si es nuevo, lo marca y lo encola.

Usa X-Shopify-Webhook-Id, y no X-Shopify-Event-Id, para descartar duplicados: si tienes dos suscripciones al mismo tema, cada entrega trae su propio Webhook-Id y las dos comparten el Event-Id. Y si el proceso que lee la cola cobra, descuenta stock o manda correos, hazlo idempotente: es la idea que usamos para evitar cobros dobles con una clave de idempotencia, con el id del webhook en el papel de la clave.

Para probarlo en local sin Shopify, arranca el servidor con SHOPIFY_API_SECRET=test_secret_do_not_use node start.mjs (un start.mjs que solo llama a app.listen(8798)) y, en otra terminal con bash (en Windows sirve Git Bash), corre bash curl.sh:

SECRET=test_secret_do_not_use # placeholder: never paste your real client secret into a script
BODY='{"id": 820982911946154508, "email": "jon@example.com"}'
HMAC=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
send() { curl -s -o /dev/null -w "$1: %{http_code}" http://localhost:8798/webhooks/shopify -H "content-type: application/json" -H "x-shopify-webhook-id: $1" -H "x-shopify-hmac-sha256: $2" -d "$3"; echo; }

send wh-1 "$HMAC" "$BODY"
send wh-1 "$HMAC" "$BODY"
send wh-2 "$HMAC" '{"id": 820982911946154508, "email": "eve@example.com"}'
send wh-3 "not-a-signature" "$BODY"

Esta es la salida que obtuvimos:

wh-1: 200
wh-1: 200
wh-2: 401
wh-3: 401
  1. HMAC es la firma de openssl dgst -sha256 -hmac en binario, pasada a base64, como la de Shopify. Para este cuerpo coincide con la que calcula Node.
  2. La primera entrega recibe 200 y se encola. La segunda repite el id wh-1: 200, pero no se encola otra vez (eso lo comprueban las pruebas, no esta salida).
  3. La tercera cambia el correo y conserva la firma; la cuarta trae una firma inventada. Las dos reciben 401.

Además pasaron 26 pruebas con el corredor de Node: diez sobre la función (incluidos el cuerpo vuelto a armar, el secreto vacío y el encabezado de otro largo), ocho contra Express con peticiones HTTP firmadas, siete contra el route handler llamado con un Request de Node 22 y una con el ejemplo de Shopify.

Errores comunes

  • Parsear antes de verificar. Un app.use(express.json()) global antes de la ruta, o un request.json() en Next.js, te dejan sin los bytes originales. JSON.stringify no los reconstruye: en nuestra prueba quitó espacios y redondeó un id.
  • Comparar sin revisar el largo. timingSafeEqual lanza un error si los largos difieren, y un encabezado ausente rompe Buffer.from. Tu endpoint responde 500 en lugar de 401.
  • Calcular el HMAC con un secreto vacío. Si falta la variable de entorno y tu código firma con "", cualquiera puede firmar igual. Rechaza siempre cuando no hay secreto.
  • Hacer el trabajo antes de responder. Shopify corta a los cinco segundos, lo cuenta como fallo y reintenta: el mismo webhook vuelve a llegar mientras el primero sigue en proceso.
  • Responder 200 a todo «para que Shopify no reintente». Si tu cola falló, ese 200 pierde el evento. Un 500 es lo correcto: Shopify lo reintenta.
  • Validar solo con el secreto nuevo al rotar. Durante la rotación, Shopify firma con el secreto más antiguo que no hayas revocado. Acepta los dos hasta revocar el viejo.
  • Olvidar el límite de tamaño. express.raw() acepta 100 KB por defecto. Si tus cuerpos pueden ser más grandes, sube limit; si no, Express rechaza la petición y Shopify lo cuenta como fallo.

Preguntas frecuentes

¿Tengo que verificar el HMAC si uso la plantilla de Shopify?

No a mano. Con la plantilla de React Router, authenticate.webhook(request) verifica la firma antes de que corra tu código. Si escribiste tu propio servidor en Express, Next.js u otro framework, la verificación es tuya.

¿Qué secreto uso para el HMAC?

El client secret de la app, en el Dev Dashboard, Settings, sección Credentials. Ni el client ID ni un token de acceso: la firma no coincidiría. Guárdalo en una variable de entorno o en un gestor de secretos, nunca en el repositorio.

¿Qué pasa con los webhooks cuando roto el client secret?

Según la guía de credenciales de Shopify, mientras el secreto viejo no esté revocado, Shopify sigue firmando con él. Acepta los dos (en nuestro código, SHOPIFY_API_SECRET y SHOPIFY_API_SECRET_OLD) y quita el viejo solo después de revocarlo. Shopify añade que puede tardar hasta una hora en firmar con el nuevo.

¿Por qué me llega el mismo webhook dos veces?

Shopify puede repetir una entrega tras un timeout o un reintento, y con dos suscripciones al mismo tema recibes una por cada una. Descarta repetidos por X-Shopify-Webhook-Id y haz idempotente el proceso que lee la cola.

Checklist

  • La ruta del webhook recibe el cuerpo crudo: express.raw() solo en esa ruta, o arrayBuffer() en Next.js.
  • Calculas HMAC-SHA256 del cuerpo crudo con el client secret y lo pasas a base64.
  • Comparas primero el largo y después con timingSafeEqual; sin secreto o sin encabezado, falla sin lanzar errores.
  • Firma inválida o ausente: 401, sin procesar nada.
  • Firma válida: encolas y respondes 200 en menos de cinco segundos.
  • Descartas duplicados por X-Shopify-Webhook-Id en un almacén compartido, y el proceso de la cola es idempotente.
  • Al rotar el client secret, aceptas el viejo y el nuevo hasta revocar el viejo.
  • Si publicas en la App Store, los tres webhooks de cumplimiento verifican el HMAC y responden 401 si falla.

Con la firma comprobada, un webhook deja de ser una URL que cualquiera puede llamar y pasa a ser un mensaje de Shopify. Lo siguiente es procesarlo bien: con una cola de trabajos en Postgres con SKIP LOCKED y un proceso idempotente, como en cómo evitar cobros dobles. Si todavía estás decidiendo si tu integración necesita una app propia, empieza por cuándo una app de Shopify a medida es lo correcto.

¿Viste esto en Instagram? Comenta HMAC en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 3 de noviembre de 2026

← Blog