Churn mit Polar-Webhooks verfolgen

Polar zeigt Churn bereits in seinem Dashboard. Wenn Sie Churn aber neben Ihren eigenen Produktdaten (Nutzung, Plan, Anmeldequelle) sehen wollen, brauchen Sie die rohen Events in Ihrer eigenen Datenbank. Die Webhooks von Polar liefern Ihnen alles, solange Sie sie so lesen, wie Polar es vorsieht.

Dieser Ratgeber ordnet die Abo-Events von Polar dem Churn zu, erklärt die Regeln zu Zustellung und Signaturen, über die Handler stolpern, und zeigt, wie Sie ein Churn-Log bauen, dem Sie vertrauen können. Er hält sich an die eigene Dokumentation von Polar: Webhook-Events, Zustellungen behandeln und überwachen, Abos verwalten, fehlgeschlagene Zahlungen zurückholen, Analytics und die Get Metrics API (alle abgerufen im November 2026).

Die Abo-Events

Die Seite zu Webhook-Events von Polar beschreibt diese Abo-Events:

Event	Was es laut Polar bedeutet	Bedeutung für Churn
`subscription.created`	Ein neues Abo	Neuer oder zurückkehrender Kunde
`subscription.active`	Ein Abo wird aktiv: ein neues bezahltes Abo oder eine wiederhergestellte Zahlung	Zahlend
`subscription.updated`	Jede Änderung am Abo, auch Verlängerungen	Zum Synchronisieren des Zustands nutzen
`subscription.canceled`	Gekündigt; der Kunde kann den Zugang bis zum Ende des Zeitraums behalten	Churn geplant
`subscription.uncanceled`	Der Kunde hat eine ausstehende Kündigung rückgängig gemacht	Geplanter Churn zurückgenommen
`subscription.past_due`	Eine Verlängerungszahlung ist fehlgeschlagen und kann noch zurückgeholt werden	Risiko für unfreiwilligen Churn
`subscription.revoked`	Der Zugang endet jetzt: Der Zeitraum eines gekündigten Abos ist abgelaufen, der Händler hat es entzogen, oder die Zahlungs-Retries sind ausgeschöpft	Churn ist eingetreten

Polar weist darauf hin, dass subscription.updated bei jeder Änderung ausgelöst wird, und empfiehlt, auf die spezifischen Events zu hören, wenn Sie nur bestimmte Übergänge brauchen. Für Churn sind die spezifischen Events klarer.

Die Reihenfolge der Events

Polar dokumentiert die Abfolgen, und sie sind für das Zählen wichtig:

Kündigung zum Periodenende: subscription.updated und subscription.canceled kommen sofort. Endet der Zeitraum, folgen subscription.updated und subscription.revoked.
Sofortiger Entzug: subscription.updated, subscription.canceled und subscription.revoked kommen zusammen.

Jedes gekündigte Abo erzeugt also sowohl ein subscription.canceled als auch ein subscription.revoked, möglicherweise einen Monat oder ein Jahr auseinander. Zählen Sie Churn bei subscription.revoked. Zählen Sie subscription.canceled getrennt als „geplante Kündigungen”, einen Frühindikator.

Freiwillig vs. unfreiwillig

subscription.revoked deckt sowohl freiwilligen Churn ab (eine Kündigung hat ihr Ende erreicht) als auch unfreiwilligen (die Zahlungs-Retries sind ausgelaufen). Um sie zu unterscheiden:

Hatte das Abo cancel_at_period_end gesetzt und ein subscription.canceled ohne späteres subscription.uncanceled, ist es freiwillig.
Ist es durch subscription.past_due gegangen, ohne zu subscription.active zurückzukehren, ist es unfreiwillig.

Die Seite zu fehlgeschlagenen Zahlungen von Polar erklärt den unfreiwilligen Weg: Nach einer fehlgeschlagenen Verlängerung wechselt das Abo auf past_due, und Polar schreibt dem Kunden mit einem Link zum Customer Portal. Es versucht es 4 Mal erneut, 2, 5, 7 und 7 Tage nach dem vorherigen Versuch (2, 7, 14 und 21 Tage nach dem ersten Fehlschlag), und entzieht das Abo, wenn alle Retries fehlschlagen oder der Ablehnungscode zeigt, dass die Zahlungsmethode nie funktionieren wird, etwa lost_card. Eine Kulanzfrist für Benefits lässt sich setzen (sofort, 2, 7, 14 oder 21 Tage ab past_due_at); sie ändert den Retry-Plan nicht.

Eine Unstimmigkeit, die Sie kennen sollten: Die Doku zum Entzug und die Webhook-Referenz von Polar beschreiben den Endstatus nach ausgeschöpften Retries unterschiedlich (canceled in der einen, unpaid in der anderen). Codieren Sie keinen davon fest; verlassen Sie sich auf das Event subscription.revoked und Ihr Log dessen, was davor kam.

Gründe kommen mit dem Abo

Hat eine Kündigung einen Grund, steht er am Abo: customer_cancellation_reason (Werte too_expensive, missing_features, switched_service, unused, customer_service, low_quality, too_complex, other) und customer_cancellation_comment (Abos verwalten). Speichern Sie sie aus dem Payload von subscription.canceled, damit Sie Churn nach Grund aufteilen können.

Regeln zur Zustellung

Laut Seite zur Zustellung von Polar:

Retries: Fehlgeschlagene Zustellungen werden bis zu 10 Mal mit exponentiellem Backoff wiederholt.
Timeout: 10 Sekunden, mit der Empfehlung, innerhalb von 2 Sekunden zu antworten und schwere Arbeit in einem Hintergrundjob zu erledigen, da das Timeout gesenkt werden kann.
Deaktivierte Endpoints: Nach 10 aufeinanderfolgenden Antworten, die nicht 2xx sind, wird der Endpoint deaktiviert, und alle Mitglieder der Organisation erhalten eine E-Mail. Die Reaktivierung erfolgt manuell in den Webhook-Einstellungen.
Firewalls: Der Bot Fight Mode von Cloudflare kann 403-Fehler verursachen; lassen Sie die Anfragen von Polar mit einer WAF-Regel zu.

Den dritten Punkt sollten Sie einplanen. Ein Deploy, der Ihren Handler für einen Nachmittag lahmlegt, kann den Endpoint deaktivieren, und nichts kommt bei Ihnen an, bis jemand ihn wieder einschaltet.

Signaturen

Dieselbe Seite erklärt, dass das Signaturverfahren davon abhängt, wann das Secret des Endpoints erstellt wurde. Secrets, die am oder nach dem 8. September 2026 (00:00 UTC) erstellt wurden, nutzen das Verfahren Standard Webhooks und werden unverändert an eine Standard-Webhooks-Bibliothek übergeben. Ältere Secrets nutzen das ursprüngliche HMAC von Polar, bei dem der vollständige whsec_-String vor der Übergabe an die Bibliothek base64-kodiert wird. Das Feld uses_standard_webhook_signature des Endpoints sagt Ihnen, was gilt, und die SDKs von Polar ab 1.0.0-alpha.19 probieren beides.

Sind Sie unsicher, prüfen Sie dieses Feld, bevor Sie stundenlang einen „signature mismatch” debuggen.

Lokales Testen

polar webhook listen in der Polar-CLI leitet die Events Ihrer Organisation an eine lokale URL weiter und zeigt das Secret, das Sie zur Prüfung nutzen (CLI-Webhooks).

Ein Churn-Log bauen

Ein Endpoint, spezifische Events. Abonnieren Sie die sieben Events aus der Tabelle oben.
Prüfen, speichern, antworten. Prüfen Sie die Signatur, schreiben Sie den rohen Payload mit Event-Typ, Abo-ID, Kunden-ID und Zeitstempel und geben Sie innerhalb weniger Sekunden 2xx zurück.
Deduplizieren. Retries bedeuten Wiederholungen. Tragen Ihre Zustellungen eine eindeutige Message-ID, nutzen Sie sie; sonst bilden Sie einen Schlüssel aus Event-Typ, Abo-ID und dem Zeitstempel der letzten Änderung des Abos und überspringen alles, was Sie schon gespeichert haben.
Im Hintergrund verarbeiten. Aktualisieren Sie Ihre Kundendaten aus dem gespeicherten Event, nie in der Anfrage.
Nur anhängen. Leiten Sie aktuellen Status und Kennzahlen aus dem Log ab, damit Sie nach einem Fehler neu abspielen können.
Den Endpoint überwachen. Alarmieren Sie bei Antworten, die nicht 2xx sind, bevor die Grenze von 10 Fehlschlägen bei Polar erreicht ist.
Abgleichen. Listen Sie wöchentlich die Abos über die API auf und vergleichen Sie sie mit Ihrem Log.

Mit den eigenen Zahlen von Polar vergleichen

Die Analytics von Polar definieren ihre Kennzahlen genau, was sie zu einer guten Gegenprobe macht:

Canceled subscriptions: von Kunden ausgelöste Kündigungen im Intervall; das Abo kann noch aktiv sein.
Churned subscriptions: Abos, deren bezahlter Zeitraum im Intervall endete.
Churn rate: gekündigte (churned) Abos im Intervall geteilt durch aktive Abos zu Beginn des Intervalls.
MRR: ohne Abos im Testzeitraum; mit pausierten und überfälligen, bis sie tatsächlich enden.

Die Get Metrics API liefert pro Intervall Felder wie active_subscriptions, churned_subscriptions, canceled_subscriptions, churn_rate und monthly_recurring_revenue, mit einer Aufschlüsselung nach Kündigungsgründen.

Übernehmen Sie dieselben Definitionen in Ihr eigenes Log, sollten Ihre Churn-Rate und die von Polar für denselben Zeitraum übereinstimmen. Tun sie es nicht, haben Sie wahrscheinlich Events verpasst, oft weil der Endpoint eine Zeit lang deaktiviert war.

Was Ihr eigenes Log ergänzt

Die Analytics von Polar beantworten „wie viel Churn”. Ihr Log, verknüpft mit Ihren Produktdaten, beantwortet „wessen Churn und warum”: Churn nach Anmeldequelle, nach Aktivierung, nach Plan, nach Kündigungsgrund, nach freiwillig vs. unfreiwillig. Dort liegt die Arbeit, die etwas bewirkt.

So geht es mit NoChurn

Polar bleibt die maßgebliche Quelle für Abos, Zahlungen und seinen Retry-Plan, und seine Analytics bleiben nützlich. NoChurn abonniert Ihre Polar-Webhooks, speichert und dedupliziert die Events, trennt freiwilligen von unfreiwilligem Churn und verknüpft sie mit eigenen Daten, die Sie per API senden. Es ergänzt einen Churn-Score von 0 bis 100 pro Kunde und die in seinem Kündigungsflow erfassten Gründe. Disputes bleiben bei Polar als Merchant of Record und werden schreibgeschützt angezeigt. Siehe NoChurn + Polar.