Churn mit Lemon-Squeezy-Webhooks verfolgen

Wenn Sie Abos über Lemon Squeezy verkaufen, läuft jedes Churn-Signal, das Sie brauchen, über seine Webhooks: Kündigungen, Abläufe, fehlgeschlagene Verlängerungen, Rückgewinnungen, Pausen. Schwierig ist nicht, sie zu empfangen. Schwierig ist, zu entscheiden, welches Ereignis was bedeutet, und sie so festzuhalten, dass Ihre Churn-Zahlen auch sechs Monate später noch aufgehen.

Dieser Ratgeber ordnet die Abo-Ereignisse von Lemon Squeezy Churn-Begriffen zu, zeigt, wie Sie sie speichern, und listet die Zustelldetails auf, an denen naive Handler scheitern. Er hält sich an die Dokumentation von Lemon Squeezy: die Webhook-Ereignistypen, die Seite zu Webhook-Anfragen, Anfragen signieren, den Leitfaden zur Synchronisierung mit Webhooks und die Referenz des Subscription-Objekts (alle abgerufen im November 2026).

Die Abo-Ereignisse

Die Seite zu Ereignistypen von Lemon Squeezy listet diese Abo-Ereignisse:

Ereignis	Was es laut Lemon Squeezy auslöst	Bedeutung für Churn
`subscription_created`	Ein neues Abo	Neuer (oder zurückkehrender) Kunde
`subscription_updated`	Jede Änderung nach der Erstzahlung	Zum Synchronisieren des Status
`subscription_cancelled`	Vom Kunden oder Store-Inhaber gekündigt; beginnt eine Kulanzfrist bis zum nächsten Abrechnungsdatum	Churn geplant, noch nicht eingetreten
`subscription_resumed`	Nach einer Kündigung wiederaufgenommen	Geplanter Churn rückgängig gemacht
`subscription_expired`	Nach einer Kündigung beendet oder sobald das Mahnwesen für `past_due`-Abos abgeschlossen ist	Churn eingetreten
`subscription_paused`	Zahlungseinzug pausiert	Kein Churn; getrennt verfolgen
`subscription_unpaused`	Zahlungseinzug wieder aufgenommen	Ende der Pause
`subscription_payment_success`	Eine erfolgreiche Zahlung	Umsatz
`subscription_payment_failed`	Eine Verlängerungszahlung ist fehlgeschlagen	Risiko für unfreiwilligen Churn
`subscription_payment_recovered`	Eine erfolgreiche Zahlung nach einer fehlgeschlagenen	Risiko behoben
`subscription_payment_refunded`	Eine Zahlung wurde erstattet	Umsatzkorrektur

Zwei davon verdienen einen genaueren Blick.

Gekündigt ist nicht abgewandert

subscription_cancelled löst aus, wenn der Kunde auf Kündigen klickt, aber das Abo läuft bis ends_at weiter. Während dieser Kulanzfrist kann es wiederaufgenommen werden, was subscription_resumed sendet. Wenn Sie Churn bei subscription_cancelled zählen, wird jedes wiederaufgenommene Abo zu einem falschen Churn, und Ihr Churn-Datum liegt um bis zu einen ganzen Abrechnungszeitraum daneben.

Zählen Sie Churn bei subscription_expired. Behalten Sie subscription_cancelled als eigene, vorlaufende Kennzahl: „in diesem Monat geplante Kündigungen”.

Ein Ereignis, zwei Arten von Churn

subscription_expired löst aus zwei sehr verschiedenen Gründen aus: bei einem Kunden, der gekündigt und ends_at erreicht hat (freiwilliger Churn), und bei einem Abo, das nach fehlgeschlagenen Zahlungen das Mahnwesen durchlaufen hat, ohne zurückgeholt zu werden (unfreiwilliger Churn). Der Ereignisname sagt Ihnen nicht, was davon zutrifft.

Um sie zu trennen, schauen Sie, was vorher kam. Enthält Ihr Log für dieses Abo ein subscription_cancelled und danach kein subscription_resumed, ist es freiwillig. Enthält es subscription_payment_failed-Ereignisse und keine Rückgewinnung, ist es unfreiwillig. Sie können auch den Zustand des Abos lesen, wenn Sie das Ereignis erhalten: Die Referenz des Subscription-Objekts zeigt neben status einen booleschen Wert cancelled.

Freiwilliger und unfreiwilliger Churn brauchen verschiedene Lösungen; diese Aufteilung ist daher das Nützlichste, was Ihr Log Ihnen liefern kann.

Wie die Anfragen aussehen

Laut der Seite zu Webhook-Anfragen:

Jede Anfrage ist ein POST mit einem JSON:API-Body: die zum Ereignis gehörende Ressource (ein Abo bei den meisten Abo-Ereignissen, eine Subscription Invoice bei den Zahlungsereignissen).
Der Header X-Event-Name trägt den Ereignisnamen.
Der Header X-Signature trägt die Signatur.
Ihr Endpunkt muss 200 zurückgeben. Jeder andere Status wird bis zu drei weitere Male mit exponentiellem Backoff wiederholt (die Dokumentation nennt als Beispiel 5, 25 und 125 Sekunden), danach gilt die Anfrage als fehlgeschlagen.

Die Webhook-Einstellungen in Ihrem Dashboard protokollieren die letzten Zustellungen mit ihren Payloads und lassen Sie sie erneut senden. Das ist Ihr Sicherheitsnetz, falls Ihr Endpunkt ausgefallen war.

Die Signatur prüfen

Anfragen signieren erklärt das Verfahren: Sie legen beim Erstellen des Webhooks ein Signing Secret fest (6 bis 40 Zeichen), und Lemon Squeezy berechnet damit einen HMAC-SHA256-Hex-Digest des Request-Bodys. Berechnen Sie den Digest auf dem rohen Body neu, nicht auf neu serialisiertem JSON, und vergleichen Sie mit einer zeitsicheren Funktion. Weisen Sie alles ab, was nicht übereinstimmt.

Zahlungsereignisse tragen Rechnungen

Die Ereignisse subscription_payment_* tragen ein Subscription-Invoice-Objekt, nicht das Abo. Es verweist auf das Abo; speichern Sie also diese ID und rufen Sie das Abo ab, wenn Sie den Status brauchen.

Ein Churn-Log Schritt für Schritt aufbauen

Ziel ist eine Tabelle, an die nur angehängt wird, mit allem, was jedem Abo passiert ist, und aus der sich jede Churn-Kennzahl neu berechnen lässt.

Legen Sie einen Endpunkt für alle Abo-Ereignisse an. Abonnieren Sie damit die Ereignisse aus der obigen Tabelle. Der Synchronisierungsleitfaden von Lemon Squeezy weist darauf hin, dass subscription_updated jede Änderung abdeckt; Sie können also nur dieses abonnieren, wenn Sie nur den Zustand wollen. Für die Churn-Verfolgung sind die spezifischen Ereignisse leichter zu durchschauen, nehmen Sie also beides.
Prüfen, dann den rohen Payload speichern. Schreiben Sie Ereignisname, Abo-ID, Kunden-ID, Zeitstempel und das rohe JSON, bevor Sie irgendetwas anderes tun.
Deduplizieren. Wiederholungen und manuelles erneutes Senden bedeuten, dass dasselbe Ereignis zweimal ankommen kann. Die von uns genutzte Dokumentation beschreibt keine eindeutige Ereignis-ID in der Anfrage; bilden Sie also Ihren eigenen Schlüssel aus Ereignisname, Ressourcen-ID und updated_at der Ressource und ignorieren Sie Wiederholungen.
Schnell antworten. Geben Sie 200 zurück, sobald das Ereignis gespeichert ist, und verarbeiten Sie es in einem Hintergrundjob. Ein langsamer Handler, der in ein Timeout läuft, löst Wiederholungen aus.
Ableiten, nicht überschreiben. Halten Sie das Log unveränderlich. Berechnen Sie „aktuellen Status” und Churn-Zahlen daraus, damit sich ein Fehler in Ihrer Logik durch erneutes Abspielen des Logs beheben lässt.
Gelegentlich abgleichen. Listen Sie einmal pro Woche die Abos über die API auf und vergleichen Sie ihre Status mit dem, was Ihr Log sagt. Jede Abweichung bedeutet ein verpasstes Ereignis.

Die Kennzahlen, die Sie berechnen können

Mit diesem Log sind diese einfach:

Kunden-Churn-Rate eines Monats: im Monat abgelaufene Abos, geteilt durch die zu Monatsbeginn aktiven Abos.
Anteil freiwillig vs. unfreiwillig: Abläufe nach der obigen Regel aufgeteilt.
Geplante Kündigungen: Ereignisse subscription_cancelled im Monat, ein Frühindikator für den Churn des nächsten Monats.
Rettungen in der Kulanzfrist: gekündigte Abos, auf die subscription_resumed folgt.
Rückgewinnungsquote bei Zahlungen: Abos mit einem subscription_payment_recovered, geteilt durch Abos mit einem subscription_payment_failed im selben Zeitraum.
Anteil pausierter Abos: Abos, die aktuell paused sind. Berichten Sie sie getrennt; sie sind weder aktive Zahler noch abgewandert.

Definieren Sie jede Kennzahl einmal schriftlich und halten Sie die Definition stabil. Eine Churn-Rate ist nur im Vergleich mit sich selbst über die Zeit nützlich.

Testen, bevor Sie ihm vertrauen

Im Testmodus von Lemon Squeezy können Sie Webhook-Ereignisse simulieren für Abos. Spielen Sie jeden Lebenszyklus damit durch: erstellen, kündigen, wiederaufnehmen, erneut kündigen und ablaufen lassen; eine fehlgeschlagene Zahlung, die zurückgeholt wird; eine, die es nicht wird. Prüfen Sie bei jedem Schritt, dass Ihr Log und Ihre Kennzahlen Ihren Erwartungen entsprechen.

So geht es mit NoChurn

Lemon Squeezy bleibt die maßgebliche Quelle für Abos und Zahlungen; NoChurn ändert daran nichts. NoChurn abonniert Ihre Lemon-Squeezy-Webhooks, speichert und dedupliziert die Ereignisse und trennt für Sie freiwilligen von unfreiwilligem Churn. Darüber hinaus ergänzt es einen Churn Score von 0 bis 100 pro Kunde, eigene Daten, die Sie per API senden, und die Antworten aus dem Kündigungsflow, die erklären, warum Menschen gehen. Streitfälle, die Lemon Squeezy als Merchant of Record bearbeitet, werden schreibgeschützt angezeigt. Siehe NoChurn + Lemon Squeezy.