Los webhooks de Stripe son la forma en que Stripe te avisa cuando algo pasa en tu cuenta: un pago se procesa, una suscripción se cancela, una tarjeta caduca. Sin webhooks, tu sistema no se entera de nada en tiempo real — solo cuando tú consultas activamente.
Si usas cualquier herramienta que se conecta con Stripe (recuperación de pagos, alertas, acceso a grupos), los webhooks son imprescindibles. Esta guía explica cómo configurarlos bien.
Qué es un webhook
Un webhook es una URL de tu servidor que Stripe llama automáticamente cada vez que ocurre un evento. Stripe envía los datos del evento (qué pasó, a quién, cuánto) y tu servidor los procesa.
Es como decirle a Stripe: «cada vez que pase algo importante, llama a esta dirección y cuéntamelo».
Los eventos que deberías escuchar
Stripe tiene decenas de tipos de eventos, pero para un negocio de suscripciones los esenciales son:
invoice.paid— un cobro se ha procesado correctamenteinvoice.payment_failed— un cobro ha falladocustomer.subscription.created— nueva suscripcióncustomer.subscription.updated— cambio en una suscripción (incluye cancelaciones programadas)customer.subscription.deleted— suscripción eliminada definitivamentecustomer.source.expiring— tarjeta próxima a caducarcustomer.dispute.created— disputa/chargeback abiertacheckout.session.expired— checkout abandonado (incluye 3DS incompleto)invoice.payment_action_required— pago requiere acción del cliente (3DS)
No necesitas escuchar todos los eventos de Stripe. Solo los que tu sistema necesita procesar.
Cómo configurarlo en Stripe
- Ve a Stripe Dashboard → Developers → Webhooks
- Click en Add endpoint
- Introduce la URL de tu webhook (la que te proporcione tu herramienta)
- Selecciona los eventos que quieres recibir
- Guarda y copia el Webhook Signing Secret (empieza por
whsec_)
El Signing Secret es importante: sirve para verificar que los eventos que llegan realmente vienen de Stripe y no de un tercero.
Verificación de firma
Cada evento que Stripe envía incluye una firma en la cabecera Stripe-Signature. Tu servidor debe verificar esa firma usando el Signing Secret antes de procesar el evento.
Si no verificas la firma, cualquiera podría enviar eventos falsos a tu URL y tu sistema los procesaría como reales. Es un riesgo de seguridad serio.
Cualquier herramienta seria que se conecte con Stripe ya hace esta verificación automáticamente. Si montas algo a medida, asegúrate de implementarla.
Errores comunes
URL incorrecta. La URL del webhook tiene que ser accesible desde internet (no localhost). Stripe necesita poder llamarla. Verifica con una herramienta como el Webhook Tester de Stripe.
No seleccionar los eventos correctos. Si tu herramienta necesita invoice.payment_failed para detectar pagos fallidos y no lo tienes seleccionado, nunca recibirá esos eventos.
Signing Secret equivocado. Cada endpoint tiene su propio Secret. Si tienes varios webhooks, asegúrate de usar el Secret correcto para cada uno.
Tiempo de respuesta excesivo. Tu servidor debe responder en menos de 20 segundos. Si tarda más, Stripe considera que falló y reintentará. Procesa el evento rápido (en segundo plano si hace falta).
No manejar duplicados. Stripe puede enviar el mismo evento más de una vez (por reintentos). Tu sistema debe detectar duplicados y no procesar el mismo evento dos veces.
Modo test vs modo live
Stripe tiene dos entornos: test y live. Los webhooks son independientes para cada uno. Configura uno para test mientras desarrollas y otro para producción.
Los eventos de test usan claves que empiezan por sk_test_ y los de producción por sk_live_. No mezcles las claves.
Cómo saber si funciona
Después de configurar el webhook, ve a Stripe Dashboard → Developers → Webhooks → tu endpoint → Recent events. Ahí ves todos los eventos enviados, si se procesaron correctamente, y los errores si los hubo.
También puedes enviar un evento de prueba desde esa misma pantalla para verificar que tu servidor responde.
Si usas Stripe Control, la URL del webhook se genera automáticamente en tu dashboard. Solo tienes que copiarla a Stripe y seleccionar los eventos. La verificación de firma, el manejo de duplicados, y el procesamiento se gestionan por ti.
Sigue leyendo
- Guía completa para recuperar ingresos recurrentes en Stripe
- Estrategias de retención en Stripe que funcionan de verdad
- Cómo contactar a un cliente que cancela su suscripción antes de que se vaya