GuíasE-commerce
Webhooks de Stripe fiables: firma, duplicados, orden y reintentos
Las cuatro reglas
- 1VerificarLa firma, sobre el cuerpo bruto, con el secreto del endpoint.
- 2DeduplicarEl identificador del evento se guarda; un duplicado se ignora.
- 3Responder rápidoUn 200 inmediato; el trabajo pesado va a una cola.
- 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.