Webhooks de Stripe en Next.js 16: firma, cuerpo crudo y eventos repetidos
Un webhook de Stripe en el App Router que verifica la firma con el cuerpo crudo, aguanta reintentos sin duplicar pagos y no depende del orden de los eventos.
Este blog es de CREA.MBA, un boilerplate de Next.js con auth, pagos y panel de admin ya montados. Ver qué incluye
El checkout de Stripe es la parte fácil. El usuario paga, Stripe le enseña una página de éxito y tú le redirigiste a /dashboard?success=1. Lo que decide si esa persona tiene acceso a lo que ha pagado es otra cosa: el webhook que Stripe manda a tu servidor unos segundos después, y que tu app tiene que recibir, verificar y guardar sin equivocarse.
En este artículo montamos ese endpoint en Next.js 16 con el App Router y Prisma, con los tres fallos que vemos una y otra vez: la firma que nunca valida, el pago que se guarda dos veces y la suscripción que se queda en un estado viejo porque los eventos llegaron desordenados.
El endpoint mínimo que funciona
En el App Router un webhook es un route handler con un POST. Lo primero que hay que hacer es leer el cuerpo tal cual llegó, como texto, antes de que nada lo toque:
// src/app/api/webhooks/stripe/route.ts
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
export async function POST(req: Request) {
const body = await req.text();
const signature = req.headers.get('stripe-signature');
if (!signature) {
return new Response('Missing signature', { status: 400 });
}
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!,
);
} catch {
return new Response('Invalid signature', { status: 400 });
}
await handleStripeEvent(event);
return Response.json({ received: true });
}Si vienes del Pages Router, te sonará el export const config = { api: { bodyParser: false } }. En el App Router no hace falta: el handler recibe un Request estándar y eres tú quien decide cómo leer el cuerpo.
Por qué falla la firma
La documentación de Stripe lo dice sin matices: la verificación necesita el cuerpo sin procesar, y cualquier manipulación hace que falle. El error clásico es este:
// ❌ La firma ya no cuadra
const json = await req.json();
stripe.webhooks.constructEvent(JSON.stringify(json), signature, secret);JSON.stringify no devuelve los mismos bytes que mandó Stripe. Cambian los espacios, el orden de algunas claves o el escapado de caracteres, y el HMAC calculado sobre ese texto ya no coincide con el de la cabecera. Con req.text() (o Buffer.from(await req.arrayBuffer())) firmas exactamente lo que llegó.
Hay otras dos causas que cuestan más de encontrar:
- El secreto equivocado. El
whsec_...que imprimestripe listenen local es distinto del que te da el dashboard para el endpoint de producción. Si copias uno en el otro entorno, ninguna firma valida. - El reloj del servidor. Las librerías de Stripe rechazan por defecto los eventos cuya marca de tiempo se aleja más de cinco minutos de la hora actual. Un VPS con el reloj desincronizado rechaza webhooks legítimos. La propia Stripe recomienda sincronizar con NTP y avisa de que poner la tolerancia a
0desactiva la comprobación por completo.
Lo que tu proxy no debería tocar
Esto no sale en los tutoriales porque la mayoría se escriben sobre un proyecto vacío. En una app real, el proxy.ts (lo que antes de Next.js 16 era middleware.ts) suele tener reglas para toda la API: un límite de peticiones, comprobación de Origin contra CSRF, redirecciones de idioma.
Stripe llama a tu webhook servidor a servidor. No manda cabecera Origin ni Referer, ni cookies. Si el proxy rechaza los POST a /api/* que llegan sin Origin, el webhook recibe un 403 en producción y en local funciona (porque en desarrollo esa comprobación suele estar relajada). Es el tipo de fallo que no ves hasta que un cliente escribe diciendo que ha pagado y no tiene acceso.
La regla es sencilla: las rutas de webhook se autentican con su firma, así que se excluyen de la validación de Origin. El límite de peticiones sí puede quedarse, con un margen generoso, porque un reenvío masivo desde el dashboard de Stripe es tráfico legítimo.
// src/proxy.ts (fragmento)
const ORIGIN_CHECK_BYPASS = ['/api/webhooks/'];
if (isApiRoute && request.method !== 'GET') {
const bypass = ORIGIN_CHECK_BYPASS.some((p) => pathname.startsWith(p));
if (!bypass) {
const originError = validateOrigin(request);
if (originError) return originError;
}
}Stripe va a mandar el mismo evento más de una vez
Stripe reintenta cualquier entrega que no reciba un 2xx. En modo live lo hace durante un máximo de tres días con espera exponencial; en el entorno de pruebas, tres veces en unas pocas horas. Y además avisa de que, a veces, un endpoint recibe el mismo evento dos veces aunque haya respondido bien.
Si tu handler hace db.payment.create() a pelo, el segundo intento falla con la restricción unique (el P2002 de Prisma) o, peor, crea un segundo registro si no tienes esa restricción. En el primer caso devuelves un error, Stripe vuelve a intentarlo, vuelve a fallar, y así durante tres días.
Hay dos formas de protegerse, y conviene usar las dos.
Escrituras idempotentes. Todo lo que guardes a partir de un evento, con upsert sobre un identificador de Stripe que tenga índice único:
await db.payment.upsert({
where: { provider_paymentId: { provider: 'STRIPE', paymentId: invoice.id } },
update: { status: 'succeeded' },
create: {
provider: 'STRIPE',
paymentId: invoice.id,
amount: invoice.amount_paid,
currency: invoice.currency,
status: 'succeeded',
},
});Registro de eventos procesados. Stripe recomienda guardar el event.id y no procesar los que ya están. Lo importante es hacerlo en la misma transacción que el trabajo. Si apuntas el id primero y el procesado falla después, el reintento se salta un evento que nunca se aplicó.
model StripeEvent {
id String @id // evt_...
type String
createdAt DateTime @default(now())
}import { Prisma } from '@/generated/prisma/client';
async function handleStripeEvent(event: Stripe.Event) {
try {
await db.$transaction(async (tx) => {
await tx.stripeEvent.create({ data: { id: event.id, type: event.type } });
await applyEvent(tx, event); // todo lo que escribe va con `tx`
});
} catch (error) {
if (
error instanceof Prisma.PrismaClientKnownRequestError &&
error.code === 'P2002'
) {
return; // ya procesado: respondemos 200 y Stripe deja de insistir
}
throw error;
}
}Si applyEvent lanza un error, la transacción deshace también el create del evento, el route handler responde 500 y Stripe lo reintenta más tarde. Es justo lo que queremos.
El orden de los eventos no está garantizado
Una suscripción nueva genera varios eventos casi a la vez: customer.subscription.created, invoice.paid, checkout.session.completed… Stripe no garantiza que te lleguen en ese orden, y también desaconseja usar el campo created para ordenarlos, porque tiene resolución de segundos y varios eventos comparten marca de tiempo.
El fallo típico es un customer.subscription.updated que llega antes que el created, encuentra la tabla vacía y no hace nada. O al revés: un updated antiguo que llega tarde y pisa el estado bueno.
La solución que menos sorpresas da es tratar el evento como un aviso de que algo ha cambiado y pedir la verdad a la API. Para las suscripciones, recuperamos el estado actual antes de abrir la transacción (una llamada HTTP dentro de una transacción interactiva de Prisma la mantiene abierta, y su tiempo límite por defecto es de cinco segundos) y guardamos eso:
// Fuera de la transacción
const sub =
event.type.startsWith('customer.subscription.')
? await stripe.subscriptions.retrieve((event.data.object as Stripe.Subscription).id)
: null;
// Dentro de la transacción, desde applyEvent
async function syncSubscription(tx: Prisma.TransactionClient, sub: Stripe.Subscription) {
const item = sub.items.data[0];
if (!item) return;
const data = {
status: sub.status,
priceId: item.price.id,
currentPeriodEnd: new Date(item.current_period_end * 1000),
cancelAtPeriodEnd: sub.cancel_at_period_end,
};
await tx.subscription.upsert({
where: { subscriptionId: sub.id },
update: data,
create: { subscriptionId: sub.id, customerId: sub.customer as string, ...data },
});
}Da igual que llegue primero el created, el updated o los dos a la vez: los dos acaban guardando lo que Stripe tiene en ese momento. Cuesta una llamada a la API por evento, que en un SaaS pequeño no se nota.
Fíjate en item.current_period_end. Desde la versión 2025-03-31.basil de la API, current_period_start y current_period_end se movieron de la suscripción a cada uno de sus items. Mucho código copiado de tutoriales anteriores lee subscription.current_period_end y recibe undefined.
Responde rápido, procesa después si hace falta
Stripe pide devolver un 2xx antes de cualquier lógica que pueda tardar. En la práctica, guardar dos filas en Postgres y una llamada a la API caben de sobra. Lo que no cabe es mandar el email de bienvenida, generar una factura en PDF o llamar a tres servicios externos dentro del handler.
Para eso, el webhook guarda lo mínimo (el pago, la suscripción) y deja el resto a un proceso aparte: una cola, un cron que recoge filas pendientes o, en el caso más simple, una función que se lanza sin esperar su resultado. Lo que importa es que un fallo enviando un email no haga que Stripe vuelva a mandar el pago.
Qué eventos escuchar para una suscripción
Con estos cubres el ciclo completo de un SaaS con suscripciones:
| Evento | Qué hacemos |
|---|---|
checkout.session.completed |
Vincular el customer de Stripe al usuario (con client_reference_id) |
customer.subscription.created / updated |
syncSubscription() |
customer.subscription.deleted |
syncSubscription(): el estado pasa a canceled y se corta el acceso |
invoice.paid |
Registrar el pago (upsert) |
invoice.payment_failed |
Registrar el intento y avisar al usuario |
Que customer.subscription.updated también llegue cuando el usuario programa la cancelación tiene su miga, y da para un artículo propio: cancelar no significa que haya que quitarle el acceso hoy.
Probarlo en local con la CLI de Stripe
stripe listen --forward-to localhost:3000/api/webhooks/stripe
# en otra terminal
stripe trigger checkout.session.completedstripe listen imprime un secreto whsec_... que va en tu .env.local. Dos pruebas que merece la pena hacer antes de subir a producción:
- Reenvía el mismo evento dos veces desde el dashboard o con
stripe events resend. En la base de datos tiene que quedar un único pago. - Llama al endpoint de producción con una petición sin firma. Tiene que responder 400. Si responde 403, algo delante del handler (el proxy, un WAF) está cortando la petición, y a Stripe le va a pasar lo mismo.
Y si usas Polar
Polar manda sus webhooks con las cabeceras de Standard Webhooks (webhook-id, webhook-timestamp y webhook-signature) y su SDK trae validateEvent para verificarlos. Ojo con los endpoints creados hace tiempo: el formato de firma es una opción de cada endpoint y los antiguos pueden seguir con el HMAC anterior de Polar, así que, si la verificación falla en uno de ellos, empieza por ahí. Lo de leer el cuerpo como texto aplica igual.
Hay una diferencia que conviene conocer. validateEvent no te devuelve el JSON tal cual: lo pasa por los esquemas del SDK, que convierten las claves a camelCase y las fechas a Date. Si lees event.data.customer_id como en los ejemplos de JSON de la documentación, vas a recibir undefined; el campo se llama event.data.customerId. Lo mejor es hacer console.log(event.data) en el primer despliegue y escribir el handler contra lo que ves.
Polar también tiene sus reglas de entrega: reintenta hasta 10 veces con espera exponencial y desactiva el endpoint tras 10 entregas fallidas seguidas. Con Stripe un 403 te cuesta reintentos; con Polar puede dejarte sin webhooks hasta que lo reactives a mano. Ya vimos la integración completa en cómo integrar Polar en Next.js.
Lo que te llevas
- El cuerpo se lee con
req.text()y se verifica antes de parsear nada. - Las rutas de webhook se autentican con la firma; sácalas de la comprobación de
Origindel proxy. - Cada escritura con
upsert, y elevent.idregistrado en la misma transacción que el trabajo. - Para las suscripciones, pide el estado actual a la API en vez de fiarte del orden de los eventos.
- Prueba un reenvío doble y una petición sin firma contra producción antes de dar el pago por bueno.
En CREA.MBA los pagos con Stripe y Polar vienen montados detrás de una misma interfaz, con los modelos de cliente, suscripción y pago ya en el esquema de Prisma, así que el trabajo empieza en las reglas de tu producto. Si todavía estás decidiendo proveedor, tienes la comparativa en Polar o Stripe para tu SaaS indie.
¿Cuál de estos tres te ha mordido a ti: la firma, el duplicado o el orden?
¿Te gustó este artículo?
Suscríbete para más tutoriales y tips sobre crear productos con IA