Webhook-Ereignisleitfaden

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 aktiv	`subscription.active`	Gibt an, dass eine Subscription jetzt aktiv ist und wiederkehrende Gebühren geplant sind.
Subscription aktualisiert	`subscription.updated`	Wird ausgelöst, wenn ein beliebiges Feld der Subscription aktualisiert wird (Echtzeit-Synchronisierung ohne Polling).
Subscription pausiert	`subscription.on_hold`	Wird ausgelöst, wenn eine Subscription aufgrund einer fehlgeschlagenen Verlängerung vorübergehend pausiert wird.
Subscription angehalten	`subscription.paused`	Wird ausgelöst, wenn eine Subscription pausiert wird.
Subscription fortgesetzt	`subscription.unpaused`	Wird ausgelöst, wenn eine pausierte Subscription fortgesetzt wird.
Subscription verlängert	`subscription.renewed`	Tritt auf, wenn eine Subscription erfolgreich verlängert wird.
Subscription-Plan geändert	`subscription.plan_changed`	Wird ausgelöst, wenn eine Subscription upgegradet, dowgegradet oder mit anderen Add-ons geändert wird.
Zahlungsmethode der Subscription aktualisiert	`subscription.update_payment_method`	Wird gesendet, wenn die Zahlungsmethode einer Subscription aktualisiert wird. Enthält die Subscription-Payload.
Subscription gekündigt	`subscription.cancelled`	Wird ausgelöst, wenn eine Subscription vom Merchant oder Kunden gekündigt wird.
Subscription fehlgeschlagen	`subscription.failed`	Gibt eine fehlgeschlagene Subscription an. Das bedeutet, dass wir kein Mandat erstellen konnten.
Subscription abgelaufen	`subscription.expired`	Wird ausgelöst, wenn eine Subscription das Ende ihrer Laufzeit erreicht und ablä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.

Auszahlungsereignisse

Diese Ereignisse verfolgen den Transfer Ihrer Gelder von Dodo Payments auf Ihr Bankkonto und entsprechen den im Dashboard angezeigten Auszahlungsstatus. Der Payload ist ein Auszahlungsobjekt mit derselben Struktur wie ein Eintrag aus GET /payouts.

Ereignisname	Ereignistyp	Beschreibung
Auszahlung erstellt	`payout.created`	Wird ausgelöst, wenn eine Auszahlung erstellt wird – entweder durch den automatischen Auszahlungszyklus oder außerhalb des regulären Zyklus.
Auszahlung in Bearbeitung	`payout.in_progress`	Tritt auf, wenn das Fälligkeitsdatum der Auszahlung erreicht ist und die Auszahlung verarbeitet wird.
Auszahlung zurückgestellt	`payout.on_hold`	Wird ausgelöst, wenn eine Auszahlung pausiert oder zur Prüfung zurückgestellt wird.
Auszahlung erfolgreich	`payout.success`	Tritt auf, wenn die Auszahlung auf Ihr Bankkonto erfolgreich verarbeitet wurde.
Auszahlung fehlgeschlagen	`payout.failed`	Wird ausgelöst, wenn eine Auszahlung fehlschlägt. Die Gelder und Gebühren werden Ihrem Wallet wieder gutgeschrieben.

Gehen Sie nicht davon aus, dass Auszahlungsereignisse endgültig oder strikt geordnet sind. payout.failed kann rechtmäßig nach payout.success eintreffen, wenn eine Bank die Überweisung zurückgibt, und payout.success kann nach payout.failed eintreffen, wenn eine fehlgeschlagene Auszahlung später wiederhergestellt wird. Behandeln Sie den Status im Payload stets als den aktuellen Status.

payout.created wurde zuvor als payout.not_initiated ausgegeben. Wenn Sie einen bestehenden Endpoint haben, der nach payout.not_initiated filtert, aktualisieren Sie den Filter auf payout.created, damit er weiterhin übereinstimmt.

Detaillierte Payload-Schemas, Feldbeschreibungen und Beispiele für Handler finden Sie unter Payout Webhooks. Diese Webhook-Ereignisse wurden entwickelt, um Merchants wichtige Aktualisierungen bereitzustellen, damit sie ihre Abläufe effektiv verwalten können. Implementieren Sie für jedes relevante Ereignis in Ihrer Webhook-Integration robuste Handler, um eine reibungslose und zuverlässige Funktionalität sicherzustellen.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Zahlungsevents

Rückerstattungsevents

Streitigkeitsevents

Abonnementsevents

Lizenzschlüsselereignisse

Ereignisse der Berechtigungsvergabe

Guthaben-Ereignisse

Wiederherstellungsereignisse

Mahnwesen-Ereignisse

Auszahlungsereignisse

​Zahlungsevents

​Rückerstattungsevents

​Streitigkeitsevents

​Abonnementsevents

​Lizenzschlüsselereignisse

​Ereignisse der Berechtigungsvergabe

​Guthaben-Ereignisse

​Wiederherstellungsereignisse

​Mahnwesen-Ereignisse

​Auszahlungsereignisse

Zahlungsevents

Rückerstattungsevents

Streitigkeitsevents

Abonnementsevents

Lizenzschlüsselereignisse

Ereignisse der Berechtigungsvergabe

Guthaben-Ereignisse

Wiederherstellungsereignisse

Mahnwesen-Ereignisse

Auszahlungsereignisse