Las pruebas locales de webhooks de Stripe te permiten validar los handlers de eventos de pago en tu máquina antes de pasar a producción. Ejecutas tu app en local, la expones mediante una URL HTTPS pública y recibes eventos reales de Stripe en modo test con la verificación de firma totalmente intacta.
Por qué los webhooks de Stripe necesitan una URL pública
Stripe entrega los eventos de webhook por la internet pública a una URL de endpoint configurada. Direcciones como 127.0.0.1:3000 son inalcanzables desde los servidores de Stripe, así que el desarrollo local necesita un puente. Un túnel a localhost asigna una URL HTTPS pública a tu proceso local sin cambios en el router ni el firewall.
Qué necesitas antes de probar
- Una cuenta de Stripe en modo test.
- Una app local con una ruta de webhook (por ejemplo
/api/webhooks/stripe). - Tu secreto de firma de webhook de Stripe configurado en variables de entorno.
- Una herramienta de túnel que preserve las cabeceras de la petición para la verificación de firma.
Paso a paso: probar webhooks de Stripe en local con PortPreview
- Inicia tu aplicación en local en el puerto deseado.
- Ejecuta
npx portpreview 3000para generar una URL HTTPS pública. - En el Dashboard de Stripe, ve a Desarrolladores → Webhooks y añade la URL del túnel junto con tu ruta de webhook.
- Selecciona los eventos que quieres probar (por ejemplo
checkout.session.completed,invoice.paid). - Dispara eventos de prueba desde el Dashboard o la CLI de Stripe e inspecciona cada entrega.
- Verifica que tu handler devuelve una respuesta 2xx y que la validación de firma pasa.
PortPreview captura cabeceras, cuerpo y estado de respuesta para que puedas depurar entregas fallidas sin adivinar solo a partir de los logs del servidor.
Validar firmas de webhook de Stripe en local
Nunca desactives la verificación de firma durante el desarrollo. Stripe firma cada payload con tu secreto de webhook, y tu handler debe validar la cabecera Stripe-Signature exactamente igual que en producción. Las herramientas de túnel que preservan las cabeceras originales te permiten probar la ruta de código real.
Fallos de firma habituales durante las pruebas locales:
- Usar el secreto de webhook equivocado (secreto del Dashboard vs. secreto de la CLI).
- Leer un cuerpo JSON ya parseado antes de la verificación en lugar del cuerpo crudo de la petición.
- Desfase de reloj que supera la ventana de tolerancia de Stripe.
Eventos que conviene probar en local
Checkout y suscripciones
Prueba checkout.session.completed, customer.subscription.created e invoice.payment_failed para confirmar el aprovisionamiento, las concesiones de acceso y la lógica de cobro pendiente.
Flujos de Connect y marketplace
Si usas Stripe Connect, valida los eventos de actualización de cuenta y las notificaciones de transferencia con cuentas conectadas de prueba antes de salir a producción.
Idempotencia y reintentos
Stripe reintenta las entregas fallidas. Usa el replay de webhooks para confirmar que tu handler procesa eventos duplicados de forma segura.
Stripe CLI vs. túnel a localhost
La CLI de Stripe puede reenviar eventos con stripe listen --forward-to, lo que funciona bien para comprobaciones rápidas. Un túnel a localhost te da una URL pública estable que puedes pegar en el Dashboard, compartir con tu equipo y usar con varios proveedores, no solo con Stripe. Muchos equipos usan ambos: la CLI para iterar rápido y los túneles para pruebas de integración que reflejan la configuración de producción.
Cuándo pasar de local a staging
Las pruebas locales cubren la lógica del handler, el parseo del payload y la validación de firma. Pasa a staging para comprobaciones específicas del entorno como secretos gestionados, migraciones de base de datos y pipelines de release de extremo a extremo. Para el trabajo diario en funciones de pago, probar webhooks de Stripe en local reduce la iteración de minutos a segundos.
Lee nuestra guía completa sobre depurar webhooks en local o únete a la lista de espera de PortPreview para flujos de túnel centrados en webhooks.