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)
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:
| Encabezado | Qué contiene | Para qué te sirve |
|---|---|---|
X-Shopify-Hmac-Sha256 | La firma HMAC en base64; solo en HTTPS | Comprobar que la entrega viene de Shopify |
X-Shopify-Topic | El tema, por ejemplo products/update | Decidir qué trabajo encolar |
X-Shopify-Shop-Domain | El dominio myshopify.com de la tienda | Saber de qué tienda es |
X-Shopify-API-Version | La versión de la API con la que se armó el cuerpo | Interpretar los campos |
X-Shopify-Webhook-Id | Una clave única por entrega | Detectar duplicados |
X-Shopify-Event-Id | Un id que comparten todas las entregas de una misma acción del comerciante | Relacionar entregas de varias suscripciones |
X-Shopify-Triggered-At | Cuándo disparó Shopify la entrega | Registrar y ordenar |
X-Shopify-Name (opcional) | El nombre que le diste a la suscripción | Distinguir 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.
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.
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);
}
- 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. - Si el cuerpo no es un
Bufferni un string, devuelvefalse. Es lo que tienes enreq.bodycuandoexpress.raw()no procesó la petición (Express dejaundefined) o cuandoexpress.json()llegó antes (un objeto). expectedes tu firma: HMAC-SHA256 del cuerpo crudo con el client secret, en base64, como la de Shopify.receivedes el encabezado tal como llegó, en bytes.- 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());
secretsjunta el secreto actual y, mientras rotas, el anterior.filter(Boolean)quita los que no están definidos: sin ninguno, toda entrega recibe 401.express.raw()va solo en esta ruta, así que aquíreq.bodyes elBufferoriginal.req.get()lee encabezados sin distinguir mayúsculas.- Si ningún secreto valida la firma, responde 401 y sale sin tocar el cuerpo.
enqueueWebhookguarda 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.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 });
}
- Los dos
importusan el alias@/de Next.js; si tu proyecto no lo tiene, usa la ruta relativa. Buffer.from(await request.arrayBuffer())lee el cuerpo una sola vez, como bytes. No llames antes arequest.json(): consume el cuerpo y te deja solo el objeto.- Con firma inválida o ausente,
401. Lo demás es igual que en Express: encolar y responder200.
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
- El primer buffer es una firma real de 44 caracteres; el segundo, un encabezado de tres.
timingSafeEqualno devuelvefalse: lanza unRangeErrorcon el códigoERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH.- 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.
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;
}
- 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.
seenguarda losX-Shopify-Webhook-Idya recibidos: Shopify avisa que la misma entrega puede llegar más de una vez, por ejemplo tras un timeout o un reintento.- Si el id ya está, no encola nada y el endpoint responde
200igual, 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
HMACes la firma deopenssl dgst -sha256 -hmacen binario, pasada a base64, como la de Shopify. Para este cuerpo coincide con la que calcula Node.- La primera entrega recibe
200y se encola. La segunda repite el idwh-1:200, pero no se encola otra vez (eso lo comprueban las pruebas, no esta salida). - 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 unrequest.json()en Next.js, te dejan sin los bytes originales.JSON.stringifyno los reconstruye: en nuestra prueba quitó espacios y redondeó un id. - Comparar sin revisar el largo.
timingSafeEquallanza un error si los largos difieren, y un encabezado ausente rompeBuffer.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, subelimit; 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, oarrayBuffer()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
200en menos de cinco segundos. - Descartas duplicados por
X-Shopify-Webhook-Iden 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
401si 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

Publicado el 3 de noviembre de 2026