Webhook-Ereignisleitfaden - Dodo Payments Documentation

Dodo Payments bietet Echtzeit-Webhooks-Benachrichtigungen, um Sie über kritische Ereignisse im Zusammenhang mit Transaktionen, Abonnements, Rückerstattungen, Streitigkeiten und der Verwaltung von Lizenzschlüsseln zu informieren. Im Folgenden finden Sie einen detaillierten Leitfaden zu diesen Ereignissen, die zur Klarheit kategorisiert sind, sowie Implementierungstipps und -überlegungen.

Zahlungsevents

Ereignisname	Ereignistyp	Beschreibung
Payment Succeeded	`payment.succeeded`	Wird ausgelöst, wenn eine Zahlung erfolgreich verarbeitet wurde.
Payment Failed	`payment.failed`	Tritt auf, wenn ein Zahlungsversuch aufgrund von Fehlern, abgelehnten Karten oder anderen Problemen fehlschlägt.
Payment Processing	`payment.processing`	Zeigt an, dass eine Zahlung derzeit verarbeitet wird.
Payment Cancelled	`payment.cancelled`	Wird ausgelöst, wenn eine Zahlung vor Abschluss storniert wird.

Rückerstattungsevents

Ereignisname	Ereignistyp	Beschreibung
Refund Succeeded	`refund.succeeded`	Wird ausgelöst, wenn eine Rückerstattung erfolgreich verarbeitet wurde.
Refund Failed	`refund.failed`	Tritt auf, wenn ein Rückerstattungsversuch aufgrund von Verarbeitungsfehlern oder anderen Problemen fehlschlägt.

Streitigkeitsevents

Ereignisname	Ereignistyp	Beschreibung
Dispute Opened	`dispute.opened`	Wird ausgelöst, wenn ein Kunde einen Streitfall eröffnet.
Dispute Expired	`dispute.expired`	Zeigt an, dass ein Streitfall ohne Lösung abgelaufen ist.
Dispute Accepted	`dispute.accepted`	Wird ausgelöst, wenn ein Händler den Streitfall akzeptiert.
Dispute Cancelled	`dispute.cancelled`	Tritt auf, wenn ein Streitfall vom Kunden oder System storniert wird.
Dispute Challenged	`dispute.challenged`	Wird ausgelöst, wenn ein Händler einen Streitfall anfechtet.
Dispute Won	`dispute.won`	Zeigt an, dass der Händler einen Streitfall erfolgreich gewonnen hat.
Dispute Lost	`dispute.lost`	Tritt auf, wenn der Händler einen Streitfall verliert.

Abonnementsevents

Ereignisname	Ereignistyp	Beschreibung
Subscription Active	`subscription.active`	Zeigt an, dass ein Abonnement nun aktiv ist und wiederkehrende Gebühren geplant sind.
Subscription Updated	`subscription.updated`	Wird ausgelöst, wenn ein beliebiges Abonnementfeld aktualisiert wird (Echtzeit-Synchronisation ohne Polling).
Subscription On Hold	`subscription.on_hold`	Wird ausgelöst, wenn ein Abonnement aufgrund einer fehlgeschlagenen Verlängerung vorübergehend pausiert wird.
Subscription Renewed	`subscription.renewed`	Tritt auf, wenn ein Abonnement erfolgreich verlängert wird.
Subscription Plan Changed	`subscription.plan_changed`	Wird ausgelöst, wenn ein Abonnement hochgestuft, herabgestuft oder mit anderen Add-ons geändert wird.
Subscription Cancelled	`subscription.cancelled`	Wird ausgelöst, wenn ein Abonnement vom Händler oder Kunden gekündigt wird.
Subscription Failed	`subscription.failed`	Gibt ein fehlgeschlagenes Abonnement an. Das bedeutet, dass wir kein Mandat erstellen konnten.
Subscription Expired	`subscription.expired`	Wird ausgelöst, wenn ein Abonnement das Ende seiner Laufzeit erreicht und ausläuft.

Lizenzschlüsselereignisse

Ereignisname	Ereignistyp	Beschreibung
License Key Created	`license_key.created`	Wird ausgelöst, wenn ein neuer Lizenzschlüssel für ein Produkt erstellt wird.

Ereignisse der Berechtigungsvergabe

Ereignisname	Ereignistyp	Beschreibung
Grant Created	`entitlement_grant.created`	Eine neue Berechtigungsvergabe wird für einen Kunden erstellt. Lizenzschlüssel-Zuweisungen erfolgen `delivered`; OAuth-basierte Zuweisungen (Discord, GitHub, Notion) erfolgen `pending`.
Grant Delivered	`entitlement_grant.delivered`	Die Erfüllung der Zuweisung ist abgeschlossen—Lizenzschlüssel ausgestellt, Dateilinks aufgelöst oder Plattformzugang gewährt.
Grant Failed	`entitlement_grant.failed`	Die Erfüllung der Zuweisung ist fehlgeschlagen; untersuchen Sie `error_code` und `error_message`.
Grant Revoked	`entitlement_grant.revoked`	Der Zugang wurde entzogen; untersuchen Sie `revocation_reason` (Abonnementzustand, Rückerstattung, Planänderung oder manuell).

Für detaillierte Payload-Schemata, Beispielereignisse und die vollständige revocation_reason-Referenz siehe Webhook zur Berechtigungsvergabe.

Guthaben-Ereignisse

Ereignisname	Ereignistyp	Beschreibung
Credit Added	`credit.added`	Wird ausgelöst, wenn einem Kunden Guthaben gewährt wird (Abonnement, einmalig, Add-on oder API).
Credit Deducted	`credit.deducted`	Tritt auf, wenn Guthaben durch Nutzung oder manuelle Abbuchung verbraucht wird.
Credit Expired	`credit.expired`	Wird ausgelöst, wenn ungenutztes Guthaben nach dem konfigurierten Ablauftzeitraum verfällt.
Credit Rolled Over	`credit.rolled_over`	Tritt auf, wenn ungenutztes Guthaben am Ende des Zyklus in einen neuen Zuschuss übertragen wird.
Rollover Forfeited	`credit.rollover_forfeited`	Wird ausgelöst, wenn Guthaben verloren geht, weil die maximale Anzahl der Übertragungen erreicht wurde.
Overage Charged	`credit.overage_charged`	Tritt auf, wenn Überziehungsgebühren für die Nutzung jenseits des Nullguthabens erhoben werden.
Overage Reset	`credit.overage_reset`	Wird ausgelöst, wenn angesammelte Überziehungsgebühren zurückgesetzt werden (zum Beispiel zu Beginn eines neuen Abrechnungszyklus).
Manual Adjustment	`credit.manual_adjustment`	Wird ausgelöst, wenn eine manuelle Gutschrift- oder Abbuchungsanpassung vorgenommen wird.
Balance Low	`credit.balance_low`	Wird ausgelöst, wenn das Guthaben unter die konfigurierte Schwelle fällt.

Wiederherstellungsereignisse

Ereignisname	Ereignistyp	Beschreibung
Abandoned Checkout Detected	`abandoned_checkout.detected`	Ausgelöst, wenn ein unvollständiger oder fehlgeschlagener Checkout nach 60 Minuten erkannt wird.
Abandoned Checkout Recovered	`abandoned_checkout.recovered`	Tritt auf, wenn ein Kunde die Zahlung über einen Wiederherstellungslink abschließt.

Für detaillierte Payload-Schemata, Feldbeschreibungen und Handler-Beispiele siehe Recovery Webhooks.

Mahnwesen-Ereignisse

Ereignisname	Ereignistyp	Beschreibung
Dunning Started	`dunning.started`	Ausgelöst, wenn ein Mahnversuch für ein Abonnement beginnt, das pausiert oder storniert wurde.
Dunning Recovered	`dunning.recovered`	Tritt auf, wenn ein Kunde seine Zahlungsmethode aktualisiert und die resultierende Abbuchung erfolgreich ist.

Für detaillierte Payload-Schemata, Feldbeschreibungen und Handler-Beispiele siehe Wiederherstellungs-Webhooks. Diese Webhook-Ereignisse sind darauf ausgelegt, Händlern wichtige Updates bereitzustellen, um ihre Abläufe effektiv zu verwalten. Implementieren Sie robuste Handler für jedes relevante Ereignis in Ihrer Webhook-Integration, um eine reibungslose und zuverlässige Funktionalität sicherzustellen.

​Zahlungsevents

​Rückerstattungsevents

​Streitigkeitsevents

​Abonnementsevents

​Lizenzschlüsselereignisse

​Ereignisse der Berechtigungsvergabe

​Guthaben-Ereignisse

​Wiederherstellungsereignisse

​Mahnwesen-Ereignisse