Medir el churn con los webhooks de Lemon Squeezy
Qué eventos de webhook de Lemon Squeezy marcan una cancelación, una expiración, un pago fallido o una recuperación, y cómo crear un registro de churn fiable.
Si vendes suscripciones con Lemon Squeezy, todas las señales de churn que necesitas pasan por sus webhooks: cancelaciones, expiraciones, renovaciones fallidas, recuperaciones, pausas. Lo difícil no es recibirlas. Es decidir qué significa cada evento y registrarlos de forma que tus cifras de churn sigan cuadrando dentro de seis meses.
Esta guía relaciona los eventos de suscripción de Lemon Squeezy con los conceptos de churn, muestra cómo guardarlos y enumera los detalles de entrega que rompen los handlers ingenuos. Se limita a la documentación de Lemon Squeezy: los tipos de eventos de webhook, la página de peticiones de webhook, firmar peticiones, la guía de sincronización con webhooks y la referencia del objeto Subscription (todas consultadas en noviembre de 2026).
Los eventos de suscripción
La página de tipos de eventos de Lemon Squeezy incluye estos eventos de suscripción:
| Evento | Qué lo dispara según Lemon Squeezy | Significado para el churn |
|---|---|---|
subscription_created |
Una suscripción nueva | Cliente nuevo (o que vuelve) |
subscription_updated |
Cualquier cambio después del pago inicial | Úsalo para sincronizar el estado |
subscription_cancelled |
Cancelada por el cliente o por el dueño de la tienda; entra en un periodo de gracia hasta la siguiente fecha de facturación | Churn programado, todavía no ocurrido |
subscription_resumed |
Reanudada después de cancelarse | Churn programado revertido |
subscription_expired |
Terminada después de cancelarse, o al completarse el dunning de suscripciones past_due |
Churn ocurrido |
subscription_paused |
Cobro en pausa | No es churn; síguelo aparte |
subscription_unpaused |
Cobro reanudado | Fin de la pausa |
subscription_payment_success |
Un pago correcto | Ingresos |
subscription_payment_failed |
Falló un pago de renovación | Riesgo de churn involuntario |
subscription_payment_recovered |
Un pago correcto después de uno fallido | Riesgo resuelto |
subscription_payment_refunded |
Un pago reembolsado | Ajuste de ingresos |
Dos de ellos merecen una mirada más atenta.
Cancelada no es perdida
subscription_cancelled se dispara cuando el cliente hace clic en cancelar, pero la suscripción sigue funcionando hasta ends_at. Durante ese periodo de gracia puede reanudarse, lo que envía subscription_resumed. Si cuentas el churn con subscription_cancelled, cada suscripción reanudada se convierte en un falso churn, y tu fecha de churn se desvía hasta un periodo de facturación completo.
Cuenta el churn con subscription_expired. Guarda subscription_cancelled como una métrica aparte y adelantada: “cancelaciones programadas este mes”.
Un evento, dos tipos de churn
subscription_expired se dispara por dos motivos muy distintos: un cliente que canceló y llegó a ends_at (churn voluntario), y una suscripción que pasó por el dunning tras pagos fallidos sin recuperarse (churn involuntario). El nombre del evento no te dice cuál.
Para separarlos, mira lo que vino antes. Si tu registro tiene un subscription_cancelled para esa suscripción y ningún subscription_resumed después, es voluntario. Si tiene eventos subscription_payment_failed y ninguna recuperación, es involuntario. También puedes leer el estado de la suscripción al recibir el evento: la referencia del objeto Subscription muestra un booleano cancelled junto a status.
El churn voluntario y el involuntario necesitan soluciones distintas, así que esta separación es lo más útil que puede darte tu registro.
Cómo son las peticiones
Según la página de peticiones de webhook:
- Cada petición es un
POSTcon un cuerpo JSON:API: el recurso relacionado con el evento (una suscripción para la mayoría de los eventos de suscripción, una subscription invoice para los eventos de pago). - La cabecera
X-Event-Namelleva el nombre del evento. - La cabecera
X-Signaturelleva la firma. - Tu endpoint debe devolver
200. Cualquier otro estado se reintenta hasta tres veces más con espera exponencial (la documentación da 5, 25 y 125 segundos como ejemplo), tras lo cual la petición se considera fallida.
La página de ajustes de webhooks de tu panel registra las entregas recientes con sus payloads y te permite reenviarlas. Es tu red de seguridad si tu endpoint estaba caído.
Verifica la firma
Firmar peticiones explica el esquema: fijas un secreto de firma al crear el webhook (de 6 a 40 caracteres), y Lemon Squeezy calcula con él un digest hexadecimal HMAC-SHA256 del cuerpo de la petición. Vuelve a calcular el digest sobre el cuerpo sin procesar, no sobre JSON reserializado, y compáralo con una función de tiempo constante. Rechaza todo lo que no coincida.
Los eventos de pago llevan facturas
Los eventos subscription_payment_* llevan un objeto subscription invoice, no la suscripción. Hace referencia a la suscripción, así que guarda ese ID y, si necesitas el estado, obtén la suscripción.
Construir un registro de churn paso a paso
El objetivo es una tabla de solo escritura (append-only) con lo que le pasó a cada suscripción, a partir de la cual se puedan recalcular todas las métricas de churn.
- Crea un único endpoint para todos los eventos de suscripción. Suscríbelo a los eventos de la tabla de arriba. La guía de sincronización de Lemon Squeezy indica que
subscription_updatedcubre todos los cambios, así que puedes suscribirte solo a él si solo quieres el estado. Para medir el churn, los eventos específicos son más fáciles de interpretar, así que usa ambos. - Verifica y guarda el payload sin procesar. Escribe el nombre del evento, el ID de la suscripción, el ID del cliente, la marca de tiempo y el JSON sin procesar antes de hacer nada más.
- Deduplica. Los reintentos y los reenvíos manuales hacen que el mismo evento pueda llegar dos veces. La documentación que usamos no describe un ID de evento único en la petición, así que crea tu propia clave a partir del nombre del evento, el ID del recurso y el
updated_atdel recurso, e ignora las repeticiones. - Responde rápido. Devuelve
200en cuanto el evento esté guardado y procésalo en un job en segundo plano. Un handler lento que agota el tiempo dispara reintentos. - Deriva, no sobrescribas. Mantén el registro inmutable. Calcula el “estado actual” y los recuentos de churn a partir de él, para que un error en tu lógica pueda corregirse reproduciendo el registro.
- Concilia de vez en cuando. Una vez a la semana, lista las suscripciones mediante la API y compara sus estados con lo que dice tu registro. Cualquier diferencia significa un evento perdido.
Las métricas que puedes calcular
Con ese registro, estas son directas:
- Tasa de churn de clientes de un mes: suscripciones que expiraron durante el mes, divididas entre las suscripciones activas al principio del mes.
- Parte voluntaria frente a involuntaria: las expiraciones separadas según la regla de arriba.
- Cancelaciones programadas: eventos
subscription_cancelleddel mes, un indicador adelantado del churn del mes siguiente. - Salvadas durante el periodo de gracia: suscripciones canceladas seguidas de
subscription_resumed. - Tasa de recuperación de pagos: suscripciones con un
subscription_payment_recovereddivididas entre las suscripciones con unsubscription_payment_faileden el mismo periodo. - Parte en pausa: suscripciones actualmente en
paused. Infórmalas por separado; no son ni clientes que pagan ni clientes perdidos.
Define cada métrica una vez, por escrito, y mantén estable la definición. Una tasa de churn solo es útil comparada consigo misma a lo largo del tiempo.
Probar antes de fiarte
El modo test de Lemon Squeezy puede simular eventos de webhook de suscripciones. Haz pasar por él cada ciclo de vida: crear, cancelar, reanudar, volver a cancelar y dejar que expire; un pago fallido que se recupera; uno que no. Comprueba que tu registro y tus métricas coinciden con lo que esperas en cada paso.
Hacerlo con NoChurn
Lemon Squeezy sigue siendo la fuente de verdad de las suscripciones y los pagos; NoChurn no los cambia. NoChurn se suscribe a tus webhooks de Lemon Squeezy, guarda y deduplica los eventos y separa por ti el churn voluntario del involuntario. Encima añade un churn score de 0 a 100 por cliente, los datos personalizados que envías por API y las respuestas del flujo de cancelación que explican por qué se va la gente. Las disputas, que Lemon Squeezy gestiona como merchant of record, se muestran en solo lectura. Consulta NoChurn + Lemon Squeezy.