Webhook de prueba de Stripe: prueba pagos en local con la CLI

La forma más rápida de ejecutar un webhook de prueba de Stripe es con la Stripe CLI. Inicias sesión, ejecutas stripe listen para reenviar eventos del modo de prueba de Stripe a una URL local y luego ejecutas stripe trigger para disparar eventos de ejemplo. Tu app recibe solicitudes reales y firmadas sin ningún deploy.

Esto importa sobre todo en apps construidas con herramientas de IA como Lovable, Bolt o Base44, donde el flujo de pago suele verse bien en una demo pero nunca se ha enfrentado a una tarjeta rechazada, un reintento o un evento duplicado. Soy un ingeniero brasileño, y esta es la rutina que uso antes de que pase dinero real por una app.

¿Cómo envío un webhook de prueba en Stripe?

Tienes tres opciones, y cada una prueba cosas distintas.

• Stripe CLI: la mejor para desarrollo local. Reenvía eventos a localhost y te permite dispararlos desde la terminal.
• Event destinations en el dashboard: en modo de prueba puedes apuntar Stripe a una URL pública y enviar un evento de prueba desde el dashboard. Útil para un despliegue de staging.
• Acciones reales en modo de prueba: completar un Checkout con una tarjeta de prueba genera exactamente la secuencia de eventos que tu app verá en producción.

En el trabajo diario combino la primera y la tercera. La CLI da feedback rápido, y un checkout de prueba real confirma toda la cadena: tu frontend, tu servidor, Stripe y de vuelta a tu base de datos.

¿Cómo uso stripe listen para reenviar eventos a localhost?

Instala la Stripe CLI y luego autentícate con stripe login. Abre el navegador para vincular la CLI con tu cuenta. Asegúrate de estar trabajando en modo de prueba.

Levanta tu app en local y luego ejecuta:

1. stripe listen –forward-to localhost:3000/api/stripe/webhook (usa tu propio puerto y tu propia ruta).
2. Copia el secreto de firma que muestra la CLI. Empieza con whsec_.
3. Pon ese valor en tu variable de entorno local para el secreto del webhook.
4. Reinicia tu app para que lea el nuevo valor.

El error más común que veo es usar en local el secreto del endpoint del dashboard. La sesión de la CLI tiene su propio secreto, así que la verificación de la firma falla con un error confuso. Si tu handler devuelve 400 en cada evento, revisa esto primero.

Confirma también que tu handler verifique la firma contra el cuerpo crudo de la solicitud. Los frameworks que parsean el JSON antes de que tu código lo vea rompen la verificación. Es un problema del código, no de Stripe.

¿Cómo disparo eventos específicos con la Stripe CLI?

Con el listener en marcha, abre una segunda terminal y ejecuta stripe trigger seguido del nombre de un evento. Los más comunes para una app de pagos:

• checkout.session.completed
• payment_intent.succeeded
• payment_intent.payment_failed
• invoice.paid e invoice.payment_failed
• customer.subscription.deleted

Observa la salida del listener. Cada línea muestra el evento y el estado HTTP que devolvió tu endpoint. Quieres un 200 para los eventos manejados, y también quieres ver tus propios logs y los cambios en la base de datos.

Una advertencia: los eventos disparados usan datos de fixture generados. No van a contener tu ID de cliente, tu ID de pedido ni tus metadatos. Así que un trigger demuestra que tu endpoint recibe y verifica eventos, pero puede que no demuestre que tu lógica de pedidos funciona. Para eso, haz un checkout de prueba real con la tarjeta 4242 4242 4242 4242 y deja que la CLI reenvíe los eventos resultantes.

¿Qué casos de falla debo probar antes del lanzamiento?

Las apps construidas con IA suelen manejar el caso de éxito. En las fallas es donde se pierden dinero y datos. Esta es la lista que recorro.

La regla clave: tu app debe otorgar acceso o marcar un pedido como pagado solo después de que un webhook verificado confirme el pago, no porque el navegador llegó a una página de éxito. Cualquiera puede abrir una URL de éxito a mano. Un escáner de seguridad genérico no va a detectar esto, porque es lógica de negocio, no un patrón de vulnerabilidad conocido.

Revisa también que los errores devuelvan un estado distinto de 2xx. Si tu handler se traga una excepción y devuelve 200, Stripe cree que el evento se manejó y no reintenta, y pierdes el registro del pago sin darte cuenta.

¿Cómo pruebo eventos duplicados y fuera de orden?

Stripe puede entregar el mismo evento más de una vez y no garantiza el orden. Tu handler debe resistir ambas cosas.

Duplicados

Usa stripe events resend con un ID de evento de tu dashboard de prueba para entregar el mismo evento otra vez. Tu app no debería crear un segundo pedido, enviar un segundo email ni extender una suscripción dos veces. La solución habitual es guardar los IDs de los eventos procesados en una tabla con una restricción de unicidad y saltarte los que ya viste. Mejor aún, haz que la actualización en sí sea idempotente, por ejemplo poniendo el estado de un pedido como pagado en lugar de incrementar un contador.

Fuera de orden

Puedes recibir invoice.paid antes que checkout.session.completed, o una actualización de suscripción antes de que exista el registro. Pruébalo reenviando eventos en otro orden, o borrando temporalmente la fila relacionada y reenviando. Un handler robusto o bien obtiene el objeto actual desde la API de Stripe, o bien falla con un 500 para que Stripe reintente más tarde.

Concurrencia

Si dos copias llegan casi en el mismo momento, un patrón de verificar y luego insertar todavía puede crear duplicados. Lo que realmente te protege es la restricción de unicidad en la base de datos, así que apóyate en ella y no solo en el código de la aplicación.

¿Cómo pruebo después de salir del constructor?

El código construido en Lovable se puede llevar a GitHub y a tu propio hosting. Cuando lo haces, la configuración del webhook cambia, y este es un punto común donde los pagos se rompen en silencio.

1. Registra un nuevo endpoint en Stripe para la nueva URL pública, primero en modo de prueba.
2. Usa el secreto del nuevo endpoint en las variables de entorno del nuevo hosting. No reutilices el secreto de la CLI ni uno antiguo.
3. Revisa dónde corre la lógica en el servidor. Si los webhooks antes corrían en una función administrada por el constructor, confirma que la misma lógica ahora existe en tu propio backend.
4. Haz un checkout de prueba completo contra la URL de staging desplegada y confirma que cambia la fila en la base de datos.
5. Repite en modo de producción con un pago real pequeño que reembolsas después, cuando todo pase.

Elimina el endpoint antiguo en Stripe cuando termines para que los eventos no se envíen a dos lugares. Quedarse en el constructor a veces es la mejor decisión, sobre todo para una app simple con poco tráfico. Pero si migras, trata el webhook como lo primero que vuelves a probar, porque el dueño de la app es responsable de la confirmación del pago incluso cuando la plataforma opera la infraestructura.

Corrige el código existente antes de considerar una reescritura. Cuando reviso un flujo de pago, empiezo buscando correcciones puntuales en el código existente antes de cualquier cosa más grande.

¿Quieres un segundo par de ojos?

Si quieres una segunda opinión sobre tu handler de webhooks o tu flujo de pago, escríbeme a me@filipeeduardo.dev con una descripción de tu configuración y te diré qué revisaría primero.