Qué webhooks de Stripe usar para seguir el churn y qué significa cada uno
Los eventos de webhook de Stripe que importan para el churn: cancelaciones, pausas, pagos fallidos, pruebas, tarjetas, disputas, y cómo guardarlos.
El Dashboard de Stripe te muestra las suscripciones tal como están ahora. El análisis del churn necesita la historia de cómo llegaron ahí: cuándo se pidió una cancelación, cuándo se hizo efectiva, si siguió a un pago fallido, si el cliente pausó antes. Esa historia está en los eventos de webhook, y si no los guardas a medida que llegan, no podrás reconstruirla después con mucha confianza.
Esta guía enumera los eventos de Stripe que importan para el churn, qué significa cada uno y qué guardar. Se basa en la guía de Stripe using webhooks with subscriptions, la visión general de los webhooks, la referencia de la API de cancelación de suscripciones, la referencia de Early Fraud Warning y el artículo de soporte de Stripe sobre el actualizador de tarjetas (todo consultado en noviembre de 2026).
La lista corta
| Evento | Qué significa para el churn |
|---|---|
customer.subscription.created |
Empezó una suscripción. No es prueba de pago. |
customer.subscription.updated |
Algo cambió: plan, cupón, renovación, una cancelación programada, una pausa del cobro |
customer.subscription.deleted |
La suscripción terminó. Este es el evento de churn. |
customer.subscription.paused |
El estado cambió a paused |
customer.subscription.resumed |
Volvió una suscripción en pausa |
customer.subscription.trial_will_end |
Una prueba termina pronto |
invoice.payment_failed |
Falló un intento de pago |
invoice.paid |
Se pagó una factura, también tras un fallo |
payment_method.automatically_updated |
El actualizador de tarjetas sustituyó los datos de la tarjeta |
charge.dispute.created |
Un cliente disputó un cargo |
radar.early_fraud_warning.created |
Un emisor marcó un cargo como posible fraude |
El resto de esta guía los recorre en el orden en que suelen ocurrir.
Empezar y cambiar
customer.subscription.created
Stripe lo envía cuando se crea una suscripción. Es el inicio de tus datos de cohortes, pero no es prueba de que el cliente haya pagado. Si la primera factura falla, la guía de webhooks dice que la suscripción se queda en incomplete. Guarda la fecha de creación, pero cuenta un cliente como captado solo cuando se pague la primera factura.
customer.subscription.updated
Stripe describe este evento como enviado cuando una suscripción empieza o cambia: renovar, añadir un cupón, aplicar un descuento, añadir un elemento de factura y cambiar de plan lo disparan. Para el churn, tres cambios dentro de él son los que más importan:
- Se programa una cancelación. Cuando
cancel_at_period_endpasa a true, el cliente ha decidido irse, aunque la suscripción siga activa. Guarda esta fecha. Es cuando se tomó la decisión, que puede ser semanas antes de que termine la suscripción. - Se retira una cancelación. Cuando
cancel_at_period_endvuelve a false, has conservado al cliente. Guárdalo también, o tus retenciones serán invisibles. - Un downgrade. Un cambio de plan a un precio más barato es contracción, el primo discreto del churn.
Como este evento se dispara por muchos motivos, compara el nuevo objeto con previous_attributes del evento para ver qué cambió realmente.
Terminar
customer.subscription.deleted
La guía de webhooks lo dice claramente: se envía cuando termina la suscripción de un cliente. Este es tu evento de churn. Su fecha es cuando se detuvieron los ingresos.
Lee cancellation_details en la suscripción, documentado en la referencia de la API de cancelación:
reasonte dice por qué terminó:cancellation_requested,payment_failedopayment_disputed, entre otros. Así separas el churn voluntario del involuntario sin adivinar.feedbackcontiene el motivo elegido por el cliente, comotoo_expensive,unused,missing_featuresoswitched_service.commentcontiene el texto libre que escribió el cliente.
Si recuerdas una sola cosa de esta guía, guarda reason y feedback en el momento de la eliminación. Para las métricas construidas encima, consulta cómo calcular la tasa de churn y churn involuntario.
Pausar
customer.subscription.paused y customer.subscription.resumed
Stripe envía customer.subscription.paused cuando el estado de una suscripción cambia a paused, también automáticamente cuando una prueba termina sin método de pago si lo configuraste así. Envía customer.subscription.resumed cuando se reanuda una suscripción en pausa, y la guía indica que no se aplica cuando solo se reanuda el cobro.
Esa distinción importa: una pausa del cobro (pause_collection) no cambia el estado, así que solo la ves a través de customer.subscription.updated. Si ofreces pausas como herramienta de retención, sigue los dos tipos. Los detalles están en cómo pausar una suscripción en Stripe.
Un cliente en pausa no se ha ido. Infórmalo por separado, y atribuye cualquier cancelación posterior al motivo original.
Pruebas
customer.subscription.trial_will_end
Stripe lo envía tres días antes de que termine una prueba, o enseguida si la prueba dura menos de tres días. Es tu último buen momento para recordárselo al cliente, comprobar que hay un método de pago registrado y asegurarte de que llegó a la parte del producto que hace que se quede. El paso de prueba a pago es una métrica de churn por derecho propio; consulta conversión de prueba a pago.
Pagos
invoice.payment_failed
Falló un intento de pago de una factura. En las renovaciones, esto abre la ventana de dunning. Guarda el número de intento, el código de rechazo y el advice code del last_payment_error del PaymentIntent; nuestra guía de los códigos de rechazo de Stripe explica qué significa cada uno.
No registres churn aquí. Un pago fallido es un riesgo, no una salida. La suscripción solo se pierde cuando se elimina, o cuando tus ajustes de recuperación la pasan a un estado en el que dejas de dar servicio al cliente.
invoice.paid
Se pagó la factura. Tras un fallo, este es tu evento de recuperación. Guarda qué intento tuvo éxito y si el cliente cambió antes su tarjeta. Con el tiempo, eso te dice si son los reintentos o los correos los que hacen la mayor parte del trabajo de recuperación.
payment_method.automatically_updated
El artículo de soporte de Stripe sobre el actualizador de tarjetas dice que Stripe crea este evento cuando el actualizador de tarjetas cambia los datos de una tarjeta. Explica una renovación que tiene éxito con una tarjeta que, si no, habría caducado. Registrarlo te permite ver cuánto churn involuntario te evita la red; más en tarjetas que caducan.
Disputas y fraude
charge.dispute.created
Un cliente disputó un cargo con su banco. Para el churn, una disputa es casi siempre el final de la relación, y Stripe registra payment_disputed como reason de la cancelación cuando una suscripción termina por ese motivo. Sigue las disputas por separado de las cancelaciones: cuestan tasas y necesitan una respuesta.
radar.early_fraud_warning.created
La referencia de Early Fraud Warning lo describe como el emisor notificando a Stripe que un cargo puede ser fraudulento. Todavía no es una disputa. Si vendes suscripciones, decide rápido si reembolsas y detienes los cargos futuros. Hablamos de esa decisión en las alertas tempranas de fraude de Stripe.
Guardar los eventos para que las cifras se sostengan
La visión general de los webhooks de Stripe documenta algunos comportamientos que determinan cómo guardar los eventos:
- Los eventos pueden llegar desordenados. Stripe no garantiza el orden de entrega. Usa la fecha
createddel evento y los propios campos del objeto, no el orden de llegada, para construir el historial. - Los eventos pueden llegar más de una vez. Elimina los duplicados por el ID del evento antes de escribir nada.
- Devuelve un 2xx rápido. Guarda el evento en bruto, confírmalo y procésalo en una tarea en segundo plano.
- Verifica las firmas. Comprueba la cabecera
Stripe-Signaturecon el secreto de tu endpoint antes de fiarte de un payload.
Una tabla sencilla funciona bien: ID del evento, tipo, fecha de creación, ID del cliente, ID de la suscripción y el payload en bruto. Deriva de ella tus tablas de churn. Cuando cambia una definición, puedes recalcular a partir de los eventos en bruto en lugar de perder el historial.
Qué derivar
- Inicio de la suscripción (primera factura pagada), cancelación pedida, cancelación retirada, terminada.
reasonyfeedbackal final.- Inicio y fin de la pausa.
- Cada pago fallido con sus códigos, y la recuperación que siguió.
- Disputas y alertas tempranas de fraude por cliente.
Hacerlo con NoChurn
NoChurn se conecta a Stripe en un clic y lee estos eventos por ti, para que no tengas que crear tú el almacenamiento descrito arriba. Los usa para los reintentos inteligentes, los correos de recuperación que revisas, las respuestas del flujo de cancelación, los correos de win-back el día 30, 60 y 90 y un score de churn de 0 a 100. Puedes añadir tus propios datos de clientes por API. Stripe sigue siendo la fuente de verdad de la facturación. Consulta NoChurn + Stripe.