GuíasE-commerce

Webhooks de Stripe fiables: firma, duplicados, orden y reintentos

Por el equipo de Banzai LabsActualizado el 3 min de lectura

StripeFirma¿Ya procesado?Respuesta 200ProcesoReenviado hasta recibirloVerificar, deduplicar, responder rápido, procesar después
Cada evento de Stripe se verifica, se deduplica, se confirma enseguida y luego se procesa.

Las cuatro reglas

  1. 1VerificarLa firma, sobre el cuerpo bruto, con el secreto del endpoint.
  2. 2DeduplicarEl identificador del evento se guarda; un duplicado se ignora.
  3. 3Responder rápidoUn 200 inmediato; el trabajo pesado va a una cola.
  4. 4Releer el estadoSi el orden es dudoso, se consulta la API de Stripe.

El endpoint

export async function POST({ request }: { request: Request }) {
  const bruto = await request.text();
  const sig = request.headers.get('stripe-signature')!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(bruto, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('firma no válida', { status: 400 });
  }
  const nuevo = await db.eventos.insertarSiNoExiste(event.id); // restricción única
  if (nuevo) await cola.añadir(event); // procesamiento asíncrono
  return new Response('ok');
}

Las trampas

Trampa Consecuencia Solución
Cuerpo JSON reescrito Firma rechazada Leer el texto bruto
Trabajo largo antes de responder Stripe reintenta, duplicados Responder y luego procesar
Sin control de duplicados Pedido creado dos veces Identificador único en base de datos
Suponer el orden de los eventos Estado incoherente Releer el objeto por la API

Escuchar solo lo útil

En el panel, suscribe el endpoint solo a los eventos que tratas (checkout.session.completed, invoice.paid, customer.subscription.deleted…).

Antes: Stripe Checkout. El principio: qué es un webhook.

Preguntas frecuentes

¿Por qué falla la verificación de firma?
Casi siempre porque el cuerpo de la petición se ha transformado (JSON analizado y reescrito) antes de verificar. Hace falta el cuerpo bruto, byte a byte.
¿Qué pasa si mi servidor está caído?
Stripe reintenta durante varios días con plazos crecientes. Los eventos perdidos siguen visibles en el panel.
¿Cómo probar en local?
Con la CLI de Stripe: stripe listen --forward-to hacia tu dirección local, y después stripe trigger para lanzar un evento.

Para leer después

Todas las guías