Webhooks de Stripe: configurar, verificar y probar
Guía de webhooks de Stripe
Webhooks de Stripe: endpoint, firma y pruebas con la CLI | We.Inc
Configura un endpoint de webhook de Stripe, verifica Stripe-Signature con el cuerpo sin procesar, prueba con stripe listen y stripe trigger, y completa los pedidos de Checkout una sola vez.
Un webhook de Stripe es un endpoint HTTPS en tu servidor al que Stripe envía por POST el JSON de un evento, como checkout.session.completed tras un pago. Tu handler debe verificar la cabecera Stripe-Signature contra el cuerpo sin procesar e intacto usando el secreto whsec_ del endpoint, devolver un 2xx rápido y tolerar que el mismo evento llegue más de una vez.
Lo esencial de los webhooks de Stripe (comprobado con la documentación de Stripe, octubre de 2026)
- Elemento
- Detalle
- Cabecera de firma
- Stripe-Signature: t=<timestamp>,v1=<hex HMAC SHA-256>
- Cadena firmada
- timestamp + "." + cuerpo de la petición sin procesar
- Tolerancia por defecto de la librería
- 5 minutos entre el timestamp y ahora
- Reintentos en modo live
- Hasta tres días con espera exponencial
- Reintentos en sandbox
- Tres veces a lo largo de unas horas
- Pruebas en local
- stripe listen --forward-to localhost:4242/webhook
La mayoría de las integraciones rotas con Stripe fallan en uno de tres puntos: el framework procesó el cuerpo antes de la verificación, el handler hizo trabajo lento y agotó el tiempo, o un evento reintentado completó un pedido dos veces. Esta guía recorre un handler que evita los tres, con un comprobador abajo que verifica una cabecera Stripe-Signature en tu navegador para que veas exactamente lo que calcula la librería.
- Crea un destino de eventos en Workbench (o con la API) que apunte a tu URL HTTPS y copia su secreto de firma whsec_.
- En tu ruta, lee el cuerpo sin procesar y pásalo, junto con la cabecera Stripe-Signature y el secreto, a constructEvent.
- Haz un switch sobre event.type, encola el trabajo y devuelve 200 de inmediato.
- Prueba en local con stripe listen --forward-to y luego lanza eventos con stripe trigger.
- El secreto que muestra stripe listen es distinto del secreto de tu endpoint en el Dashboard. Usa el correcto en cada entorno.
- Los endpoints de prueba y de producción tienen secretos distintos aunque la URL sea la misma.
- Suscríbete solo a los tipos de evento que gestionas; escuchar todo añade carga para nada.
- Excluye la ruta del webhook del middleware CSRF en frameworks como Rails o Django.
- Stripe considera una redirección como entrega fallida. Registra la URL final, incluida la barra final que espera tu servidor.
Preguntas frecuentes
¿Por qué recibo "No signatures found matching the expected signature"?
Casi siempre porque el cuerpo se modificó antes de la verificación, por ejemplo con express.json() o un body parser que vuelve a codificar el JSON. Monta express.raw({ type: "application/json" }) solo en la ruta del webhook, o lee request.text() en un route handler de Next.js. Un secreto incorrecto provoca el mismo mensaje.
¿Qué eventos necesito para Stripe Checkout?
checkout.session.completed para pagos con tarjeta, más checkout.session.async_payment_succeeded para métodos diferidos como los adeudos bancarios. Stripe también sugiere gestionar checkout.session.async_payment_failed para poder avisar al cliente. Comprueba el payment_status de la sesión antes de completar el pedido.
¿Puedo fiarme de la página de éxito en lugar de un webhook?
No. La propia documentación de Stripe dice que un cliente puede pagar y cerrar la pestaña antes de que cargue tu página de éxito. Usa la página de éxito para una confirmación rápida si quieres, pero el webhook también debe activar la entrega, y ambos caminos deben poder ejecutarse dos veces sin problema.
¿Los eventos de Stripe llegan en orden?
Stripe no garantiza el orden. invoice.paid puede llegar antes que customer.subscription.created. Registra los ids de evento para detectar duplicados y obtén el objeto relacionado desde la API cuando necesites su estado más reciente.
¿Cómo reenvío un evento fallido?
Haz clic en Resend en el evento dentro del Dashboard (funciona hasta 15 días después de su creación) o ejecuta stripe events resend <event_id> --webhook-endpoint=<endpoint_id> con la CLI (hasta 30 días). Los reintentos automáticos continúan de todos modos.
La regla del cuerpo sin procesar
- Stripe calcula un HMAC SHA-256 sobre el timestamp, un punto y los bytes exactos que envió. Si algo procesa ese JSON y lo vuelve a convertir en cadena, los espacios o el orden de las claves pueden cambiar y la firma deja de coincidir.
- En Express eso significa express.raw en esta única ruta, colocado antes de que se ejecute cualquier parser JSON global. En un handler del App Router de Next.js, usa await request.text() y pasa la cadena; nunca request.json().
Responde primero, trabaja después
- Stripe solo espera la respuesta un rato corto, y con un success_url de Checkout retiene al cliente hasta 10 segundos esperando tu respuesta a checkout.session.completed. Guarda el id del evento, envía el trabajo a una cola, devuelve 200 y después manda los emails y actualiza los registros en segundo plano.
Completa el pedido exactamente una vez
- Tu función de entrega puede ejecutarse varias veces para una misma Checkout Session, a veces en el mismo instante, por un reintento más la página de éxito. Guarda un indicador de completado asociado al id de sesión dentro de una transacción y omite el trabajo si ya está marcado.
Código del handler
Express con stripe-node
express.raw se monta solo en esta ruta, así el cuerpo llega a constructEvent con los bytes originales.
Route handler del App Router de Next.js
request.text() da el cuerpo sin procesar. Si constructEvent lanza un error, la firma o el secreto son incorrectos.
Pruebas con la CLI de Stripe
Reenviar y lanzar eventos en local
listen muestra un secreto whsec_ para esta sesión. Ponlo en tu entorno local y luego lanza eventos en una segunda terminal.
Eventos que conviene gestionar
Tipos de evento comunes de Stripe y qué hacer
- Evento
- Cuándo se dispara
- Acción típica
- Un cliente terminó Checkout o un Payment Link
- Completa el pedido si payment_status no es unpaid
- Un método de pago diferido se confirmó más tarde
- Completa el pedido ahora
- Un pago diferido falló
- Envía un email al cliente
- Se pagó un PaymentIntent
- Marca el pedido como pagado (flujos de pago personalizados)
- Se pagó una factura de suscripción
- Amplía el acceso para el periodo
Comprobador de Stripe-Signature
Pega una cabecera Stripe-Signature, el cuerpo sin procesar y tu secreto whsec_ para ver la misma comprobación que hacen las librerías. Se ejecuta en tu navegador con Web Crypto y no envía nada. Usa un secreto de modo de prueba, nunca uno de producción.
Cabecera Stripe-Signature
Cuerpo de la petición sin procesar
Secreto del endpoint (whsec_...)
Tolerancia en segundos
Firmar este cuerpo ahora
Verificar
Resultado
La cabecera no tiene timestamp t=.
La cabecera no tiene firma v1=.
v1 esperado: {v}
La firma coincide.
La firma no coincide: el cuerpo se modificó o el secreto es incorrecto.
El timestamp tiene {n} segundos, dentro de la tolerancia.
El timestamp tiene {n} segundos, fuera de la tolerancia: una librería lo rechazaría.
Crea tu sitio gratis · Gratis para crear, sin tarjeta
Relacionado: Guías
- Ejemplos de datos estructurados
- Subdominio o subdirectorio
- Alternativas a Supabase
- Supabase login
- Supabase CLI
- Servidor MCP de Supabase
- Precios de Supabase
- Supabase vs Firebase para apps web
Producto
Para quién es
- Para agencias
- Para freelancers
- Para proveedores de hosting
- Para plataformas SaaS
- Para startups
- Servicios financieros
- Soluciones para salud
Funciones
Recursos
- Blog
- Centro de Ayuda
- Herramientas gratuitas para empresas
- Free UI Components
- Plantillas
- Colecciones de plantillas
- Ejemplos de webs
- Guías
- Comparativas
- Alternativas
- Los mejores
- Reseñas
- Guías de precios
- Casos de uso
- Glosario y guías
- Integraciones
- Desarrolladores
- Benchmark
- Windows App