MÉTRICAS DE CHURNLEMON SQUEEZY

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.

Publicado el 6 min de lectura

Medir el churn con los webhooks de Lemon Squeezy

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 POST con 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-Name lleva el nombre del evento.
  • La cabecera X-Signature lleva 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.

  1. 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_updated cubre 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.
  2. 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.
  3. 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_at del recurso, e ignora las repeticiones.
  4. Responde rápido. Devuelve 200 en cuanto el evento esté guardado y procésalo en un job en segundo plano. Un handler lento que agota el tiempo dispara reintentos.
  5. 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.
  6. 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_cancelled del 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_recovered divididas entre las suscripciones con un subscription_payment_failed en 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.

PROMPT

Read https://www.nochurn.sh/llms.txt,
then follow https://docs.nochurn.sh/quickstart/
to add NoChurn to this app. Use a test key
(nc_test_…) until I say we go live.

Deja de perder ingresos.

  • Gratis hasta 300 € de MRR
  • Sin tarjeta
  • Listo en 10 minutos
  • Sin comisión