Falla la verificación de la firma del webhook de Stripe — descubre por qué

Depura tu firma de Stripe

Stripe está seleccionado por defecto. El HMAC se calcula en tu navegador con WebCrypto: tu whsec_ nunca sale de la pestaña.

Anatomía de la cabecera Stripe-Signature

Cada webhook de Stripe llega con una cabecera como esta. Cada campo separado por comas tiene su función:

Stripe-Signature: t=1614556800,
  v1=5257a869e7ecebeda32affa62cdca3fa51cad7414a563a8c6e3c4b41c2b7f2c8,
  v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

La cadena firmada es `${t}.${rawBody}`, no el cuerpo solo. Olvida el prefijo t. en un verificador hecho a mano y todas las firmas fallan, incluso con el secreto correcto.

Las 6 causas de fondo, en el orden en que comprobarlas

Ordenadas según la frecuencia con que son las culpables. Cada una tiene una pista que la distingue de las demás.

El arreglo del cuerpo en bruto, framework por framework

La causa n.º 1 es casi siempre esta: tu framework web leyó, parseó y re-serializó el JSON antes de que constructEvent lo viera. El JSON re-serializado tiene otros espacios, así que el HMAC deja de coincidir. Así se le pasan los bytes intactos a cada framework.

// La ruta del webhook DEBE ir antes de express.json()
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);
app.use(express.json()); // todo lo demás

export async function POST(req: Request) {
  const body = await req.text();            // en bruto, intacto
  const sig = req.headers.get('stripe-signature')!;
  const event = stripe.webhooks.constructEvent(
    body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

import { buffer } from 'micro';
export const config = { api: { bodyParser: false } };

export default async function handler(req, res) {
  const raw = await buffer(req);
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(
    raw, sig, process.env.STRIPE_WEBHOOK_SECRET
  );
  res.json({ received: true });
}

Pega los bytes exactos en el depurador de arriba: si la firma solo coincide cuando quitas un salto de línea final o un campo recodificado, el cuerpo se modificó por el camino — no es tu secreto.

Modo test frente a modo live: el secreto que parece correcto pero no lo es

Stripe te da tres valores whsec_ distintos y es fácil cruzarlos. Primero, el secreto del endpoint de test, que se muestra en el Dashboard cuando estás en modo test. Segundo, el secreto del endpoint live: un valor distinto en el mismo endpoint pasado a live. Tercero, el secreto de la CLI que imprime stripe listen, distinto otra vez y válido solo para los eventos reenviados por esa sesión. Los tres producen un HMAC de aspecto válido, así que el error es el mismo No signatures found genérico: nada dice modo equivocado. La pista: los pagos de prueba verifican y los reales dan 400. Solución: lee el secreto del endpoint exacto, en el modo exacto, que recibe el tráfico.

La ventana de replay de 5 minutos que todo el mundo olvida

constructEvent no solo comprueba el HMAC: rechaza cualquier evento cuyo timestamp t= tenga más de 300 segundos, lanzando Timestamp outside the tolerance zone. Te muerde cuando reenvías un evento capturado horas después o cuando el reloj de tu servidor se ha desviado. La firma es perfectamente válida; lo que falla es la antigüedad. El depurador de arriba muestra la antigüedad del timestamp para que distingas un replay caducado de una discrepancia real de firma. Si de verdad necesitas una ventana más larga, constructEvent acepta un cuarto argumento tolerance en segundos — pero arregla antes el reloj.

¿Es tu handler o tu secreto? Genera un evento que sabes que es válido

Cuando el depurador dice que el secreto es correcto pero producción sigue dando 400, el bug está en cómo tu handler lee el cuerpo. Aíslalo: nuestro Signer genera un payload firmado para Stripe con un secreto que controlas tú, así que puedes hacer POST de un evento garantizado como válido directamente a tu handler local. Si pasa, tu código de verificación está bien y el problema es el secreto o el middleware. Si falla, el handler está modificando el cuerpo: vuelve a la tabla del cuerpo en bruto de arriba.

Lista de diagnóstico

Recórrela en orden la próxima vez que constructEvent lance una excepción.

1. Pega el whsec_, el cuerpo en bruto y el Stripe-Signature que fallan en el depurador de arriba: te dice la causa antes de que sigas leyendo.
2. Confirma que el cuerpo que llega a constructEvent es la cadena en bruto intacta, no un objeto parseado y re-serializado.
3. Copia el secreto de firma directamente de la página del endpoint en el Dashboard: no de stripe listen, ni de otro endpoint.
4. Comprueba que usas el secreto live para el tráfico live y el secreto de test para el tráfico de test.
5. Registra req.headers['stripe-signature'] y confirma que está presente y que ningún proxy lo ha truncado.
6. Comprueba que el timestamp t= del evento no tiene más de 5 minutos (replay caducado o reloj desviado).

Captura y reenvía el evento real que falla

¿Sigues atascado? Apunta Stripe a un Relay de Webhook Toolkit o a una URL de captura, atrapa la petición exacta que falla e inspecciona el cuerpo en bruto y las cabeceras byte a byte — luego reenvíala a tu handler tantas veces como necesites sin esperar a otro evento real.

Preguntas frecuentes