Abonnement- und Zahlungsereignisse über Webhooks

Historischer Rückblick: November 2025 bis August 2026; zwischen Februar und August 2026 geändert

Dieser Artikel wurde nachträglich verfasst und beschreibt die Funktion, wie sie im angegebenen Zeitraum erweitert wurde. Aus den grundlegenden Abonnementereignissen wurden Webhooks für Fortsetzung, Zahlungsfehler und Zahlungsergebnisse. Den aktuellen Ereigniskatalog und Vertrag finden Sie im Leitfaden zur öffentlichen API und zu Webhooks (Markdown-fil, AI-agentvenlig).

Webhooks benachrichtigen ein externes System, wenn Alunta eine Änderung erfasst. Sie eignen sich, wenn ein Kundenportal, CRM oder Buchhaltungssystem Abonnements verfolgen muss, ohne Alunta ständig abzufragen. Ein Ereignis signalisiert einen Zustand in Alunta; es bestätigt nicht, dass Ihr eigenes System die Folgeaktion abgeschlossen hat.

Wichtige Ereignisse

Zum Lebenszyklus gehören subscription.started, subscription.ended und subscription.resumed. Kündigung und Ende sind verschieden: Eine Kündigung kann planen oder kennzeichnen, dass eine Vereinbarung enden soll; das Ende bedeutet, dass das Abonnement tatsächlich beendet wurde. Später wurden subscription.payment_succeeded und subscription.payment_failed ergänzt, damit Integrationen auf einzelne Zahlungsergebnisse reagieren können. payment_succeeded bestätigt die Zahlung selbst; bei einer Teilzahlung oder Rate kann ein Rechnungsrest offenbleiben. invoice.paid beschreibt den Zahlungsstatus einer Rechnung und darf nicht als Beweis dafür behandelt werden, dass ein Abonnement aktiv ist.

Verwenden Sie den dokumentierten Ereignistyp und den dafür bereitgestellten Deduplizierungsschlüssel. subscription.started, subscription.ended, subscription.payment_succeeded und invoice.paid haben für Wiederholungen und Wiedergaben eine stabile data.event_id. subscription.payment_failed kann bei getrennten Wiederholungsversuchen mehrfach eintreffen und hat keine stabile event_id; bewahren Sie jede Zustellung auf und verwenden Sie, sofern verfügbar, die dokumentierte webhook_uuid als Zustellkennung. Abonnieren Sie nur Ereignisse, die Ihre Integration benötigt, und verwenden Sie für Felder und Statuswerte stets die aktuelle öffentliche API-Referenz.

Erste Schritte

1. Aktivieren Sie für das Team die API-/Webhook-Funktion und richten Sie einen HTTPS-Empfänger ein.
2. Registrieren Sie den Endpunkt und wählen Sie benötigte Abonnement- und Zahlungsereignisse aus.
3. Prüfen Sie die Signatur anhand des unveränderten Anfrageinhalts, bevor Sie die Payload verarbeiten.
4. Speichern Sie den für den jeweiligen Ereignistyp dokumentierten Schlüssel und verarbeiten Sie ihn idempotent. Verwenden Sie data.event_id für Ereignistypen mit stabilem Schlüssel, bewahren Sie einzelne Versuche von subscription.payment_failed auf und nutzen Sie, sofern verfügbar, webhook_uuid als Zustellkennung. Eine wiederholte Zustellung muss denselben Endzustand wie die erste ergeben, ohne getrennte Zahlungsversuche zusammenzuführen.
5. Antworten Sie schnell mit einem erfolgreichen HTTP-Status und führen Sie umfangreichere Verarbeitung anschließend aus.

Wenn ein Abonnement beginnt, endet, fortgesetzt wird oder eine fehlgeschlagene Zahlung hat, verwenden Sie den passenden stabilen Schlüssel und die Abonnement- und Rechnungsbeziehungen in der Payload, um Ihre lokale Ansicht zu aktualisieren. Verwenden Sie Ereignistyp und Beziehungen gemeinsam; leiten Sie Geschäftsregeln nicht allein aus der Zustellreihenfolge ab.

Häufige Fragen

Warum kam dasselbe Ereignis erneut an? Nach einem Fehler oder Timeout können Zustellungen wiederholt werden. Deduplizieren Sie anhand von data.event_id, wenn der jeweilige Ereignistyp dies dokumentiert, oder verwenden Sie webhook_uuid, sofern verfügbar, als Zustellkennung. Einzelne Zahlungsausfallversuche bleiben getrennt, auch wenn sie dasselbe Abonnement betreffen.

Ist payment_failed dasselbe wie eine Kündigung? Nein. Es ist ein Zahlungsergebnis. Lesen Sie den aktuellen Abonnementstatus separat aus.

Was soll ich tun, wenn der Empfänger nicht erreichbar war? Öffnen Sie das Zustellprotokoll, beheben Sie den Fehler am Empfänger und spielen Sie die fehlgeschlagene Zustellung erneut ab, sobald die Integration bereit ist.

Den aktuellen Ablauf finden Sie im Leitfaden zur öffentlichen API und zu Webhooks (Markdown-fil, AI-agentvenlig).

Ereignis passend zum Geschäftsbedarf auswählen

Ein Kundenportal kann auf subscription.started hören, um Zugriff einzurichten, auf subscription.ended, um eine Vereinbarung zu schließen, und auf subscription.resumed, um sie erneut zu öffnen. Ein Buchhaltungssystem kann invoice.paid verwenden, um eine Forderung als bezahlt zu markieren. Ein Support- oder Zahlungssystem kann mit subscription.payment_succeeded und subscription.payment_failed Zahlungsergebnisse anzeigen. Verwechseln Sie die Ereignisse nicht: Eine Teilzahlung bedeutet nicht zwingend, dass die Rechnung bezahlt ist, und ein Zahlungsausfall ist nicht selbst eine Kündigung.

Speichern Sie lokal den Ereignistyp, den relevanten Schlüssel und die Empfangszeit. Führen Sie die Geschäftsaktion erst nach Signaturprüfung aus. Trifft dieselbe stabile event_id erneut ein, antwortet der Empfänger trotzdem erfolgreich, überspringt aber die bereits abgeschlossene Aktion. Führen Sie getrennte Zustellungen bei Zahlungsfehlern nicht zusammen, nur weil sie dieselbe Abonnement-UUID haben. Treffen Ereignisse in unerwarteter Reihenfolge ein, rufen Sie den aktuellen Status von Abonnement oder Rechnung ab, bevor Sie den lokalen Status ändern.

Warum kam kein Ereignis an? Prüfen Sie Endpunkt, ausgewähltes Ereignis, API-Zugriff des Teams und Zustellprotokoll. Eine Produktfunktion ist nicht automatisch ein Webhook, bevor das Ereignis im öffentlichen Vertrag existiert.

Kann ein Webhook eine Aktion auslösen? Ja, in Ihrem System. Machen Sie die Aktion idempotent und zeigen Sie, auf welchen Alunta-Status sie sich stützt.