Medir el churn con los webhooks de Polar
Qué eventos de webhook de Polar marcan una cancelación, una revocación, un pago fallido o una recuperación, cómo van la entrega y las firmas, y el registro.
Polar ya muestra el churn en su panel. Pero si quieres el churn junto a tus propios datos de producto (uso, plan, origen del registro), necesitas los eventos sin procesar en tu propia base de datos. Los webhooks de Polar te lo dan todo, siempre que los leas como Polar pretende.
Esta guía relaciona los eventos de suscripción de Polar con el churn, explica las reglas de entrega y de firma que hacen tropezar a los handlers y muestra cómo construir un registro de churn fiable. Se limita a la documentación de Polar: eventos de webhook, gestionar y vigilar las entregas, gestionar suscripciones, recuperar pagos fallidos, Analytics y la Get Metrics API (todas consultadas en noviembre de 2026).
Los eventos de suscripción
La página de eventos de webhook de Polar describe estos eventos de suscripción:
| Evento | Qué significa según Polar | Significado para el churn |
|---|---|---|
subscription.created |
Una suscripción nueva | Cliente nuevo o que vuelve |
subscription.active |
Una suscripción pasa a activa: una suscripción de pago nueva, o un pago recuperado | Paga |
subscription.updated |
Cualquier cambio en la suscripción, incluidas las renovaciones | Úsalo para sincronizar el estado |
subscription.canceled |
Cancelada; el cliente puede conservar el acceso hasta el final del periodo | Churn programado |
subscription.uncanceled |
El cliente revirtió una cancelación pendiente | Churn programado revertido |
subscription.past_due |
Falló un pago de renovación y todavía puede recuperarse | Riesgo de churn involuntario |
subscription.revoked |
El acceso termina ahora: terminó el periodo de una suscripción cancelada, el comercio la revocó o se agotaron los reintentos de pago | Churn ocurrido |
Polar indica que subscription.updated se dispara con cada cambio y sugiere escuchar los eventos específicos cuando solo necesitas ciertas transiciones. Para el churn, los eventos específicos son más claros.
El orden de los eventos
Polar documenta las secuencias, y son importantes para contar:
- Cancelación al final del periodo:
subscription.updatedysubscription.canceledllegan de inmediato. Cuando termina el periodo, siguensubscription.updatedysubscription.revoked. - Revocación inmediata:
subscription.updated,subscription.canceledysubscription.revokedllegan juntos.
Así que cada suscripción perdida produce a la vez un subscription.canceled y un subscription.revoked, quizá con un mes o un año de diferencia. Cuenta el churn con subscription.revoked. Cuenta subscription.canceled por separado como “cancelaciones programadas”, un indicador adelantado.
Voluntario frente a involuntario
subscription.revoked cubre tanto el churn voluntario (una cancelación que llegó a su fin) como el involuntario (se agotaron los reintentos de pago). Para distinguirlos:
- Si la suscripción tenía
cancel_at_period_endfijado y unsubscription.canceledsin unsubscription.uncanceledposterior, es voluntario. - Si pasó por
subscription.past_duesin volver asubscription.active, es involuntario.
La página de pagos fallidos de Polar explica la vía involuntaria: tras una renovación fallida, la suscripción pasa a past_due y Polar escribe al cliente con un enlace al Customer Portal. Reintenta 4 veces, 2, 5, 7 y 7 días después del intento anterior (2, 7, 14 y 21 días después del primer fallo), y revoca si todos los reintentos fallan o si el código de rechazo muestra que el método de pago nunca funcionará, como lost_card. Puede fijarse un periodo de gracia para los beneficios (inmediato, 2, 7, 14 o 21 días desde past_due_at); no cambia el calendario de reintentos.
Una incoherencia que conviene conocer: la documentación de revocación de Polar y su referencia de webhooks describen de forma distinta el estado final tras agotarse los reintentos (canceled en una, unpaid en la otra). No fijes ninguno en el código; apóyate en el evento subscription.revoked y en tu registro de lo que vino antes.
Los motivos vienen con la suscripción
Cuando una cancelación tiene un motivo, está en la suscripción: customer_cancellation_reason (valores too_expensive, missing_features, switched_service, unused, customer_service, low_quality, too_complex, other) y customer_cancellation_comment (gestionar suscripciones). Guárdalos a partir del payload de subscription.canceled para poder desglosar el churn por motivo.
Reglas de entrega
Según la página de entrega de Polar:
- Reintentos: las entregas fallidas se reintentan hasta 10 veces con espera exponencial.
- Tiempo de espera: 10 segundos, con la recomendación de responder en 2 segundos y hacer el trabajo pesado en un job en segundo plano, ya que el tiempo de espera puede reducirse.
- Endpoints desactivados: tras 10 respuestas seguidas distintas de 2xx, el endpoint se desactiva y todos los miembros de la organización reciben un correo. Reactivarlo es manual, en los ajustes de webhooks.
- Cortafuegos: el Bot Fight Mode de Cloudflare puede provocar fallos 403; permite las peticiones de Polar con una regla del WAF.
El tercer punto es el que hay que prever. Un despliegue que rompe tu handler durante una tarde puede desactivar el endpoint, y no te llega nada hasta que alguien lo vuelve a activar.
Firmas
La misma página explica que el esquema de firma depende de cuándo se creó el secreto del endpoint. Los secretos creados el 8 de septiembre de 2026 (00:00 UTC) o después usan el esquema Standard Webhooks y se pasan tal cual a una librería de Standard Webhooks. Los secretos más antiguos usan el HMAC original de Polar, en el que la cadena completa del secreto whsec_ se codifica en base64 antes de dársela a la librería. El campo uses_standard_webhook_signature del endpoint te dice cuál se aplica, y los SDK de Polar desde la 1.0.0-alpha.19 prueban los dos.
Si dudas, revisa ese campo antes de pasarte horas depurando un “signature mismatch”.
Pruebas en local
polar webhook listen de la CLI de Polar reenvía los eventos de tu organización a una URL local y muestra el secreto que usar para la verificación (webhooks en la CLI).
Construir un registro de churn
- Un endpoint, eventos específicos. Suscríbete a los siete eventos de la tabla de arriba.
- Verifica, guarda y responde. Comprueba la firma, escribe el payload sin procesar con el tipo de evento, el ID de la suscripción, el ID del cliente y la marca de tiempo, y devuelve un 2xx en un par de segundos.
- Deduplica. Los reintentos implican repeticiones. Si tus entregas llevan un ID de mensaje único, úsalo; si no, crea una clave a partir del tipo de evento, el ID de la suscripción y la marca de tiempo de la última modificación de la suscripción, y sáltate todo lo que ya hayas guardado.
- Procesa en segundo plano. Actualiza tus registros de clientes a partir del evento guardado, nunca dentro de la petición.
- Mantenlo de solo escritura (append-only). Deriva el estado actual y las métricas del registro, para poder reproducirlo tras un error.
- Vigila el endpoint. Alerta de las respuestas distintas de 2xx antes de llegar al límite de 10 fallos de Polar.
- Concilia. Cada semana, lista las suscripciones mediante la API y compáralas con tu registro.
Compara con las cifras de Polar
Los Analytics de Polar definen sus métricas con precisión, lo que los convierte en una buena comprobación cruzada:
- Canceled subscriptions: cancelaciones solicitadas por los clientes en el intervalo; la suscripción puede seguir activa.
- Churned subscriptions: suscripciones cuyo periodo de pago terminó en el intervalo.
- Churn rate: suscripciones perdidas en el intervalo divididas entre las suscripciones activas al principio del intervalo.
- MRR: excluye las suscripciones en prueba; incluye las que están en pausa o vencidas hasta que terminan de verdad.
La Get Metrics API devuelve por intervalo campos como active_subscriptions, churned_subscriptions, canceled_subscriptions, churn_rate y monthly_recurring_revenue, con un desglose de los motivos de cancelación.
Si adoptas las mismas definiciones en tu propio registro, tu tasa de churn y la de Polar deberían coincidir para el mismo periodo. Cuando no coinciden, probablemente te has perdido eventos, a menudo porque el endpoint estuvo desactivado un tiempo.
Lo que añade tu propio registro
Los analytics de Polar responden a “cuánto churn”. Tu registro, cruzado con tus datos de producto, responde a “el churn de quién y por qué”: churn por origen del registro, por activación, por plan, por motivo de cancelación, voluntario frente a involuntario. Ahí está el trabajo que se puede accionar.
Hacerlo con NoChurn
Polar sigue siendo la fuente de verdad de las suscripciones, los pagos y su calendario de reintentos, y sus analytics siguen siendo útiles. NoChurn se suscribe a tus webhooks de Polar, guarda y deduplica los eventos, separa el churn voluntario del involuntario y los cruza con los datos personalizados que envías por API. Añade un churn score de 0 a 100 por cliente y los motivos recogidos en su flujo de cancelación. Las disputas siguen en Polar como merchant of record y se muestran en solo lectura. Consulta NoChurn + Polar.