Skip to main content
Webhook-Titelbild
Webhooks liefern Echtzeitbenachrichtigungen, wenn Ereignisse in Ihrem Dodo Payments-Konto auftreten. Verwenden Sie sie, um Workflows zu automatisieren, Ihre Datenbank zu aktualisieren, Benachrichtigungen zu senden und Ihre Systeme synchron zu halten.
Dodo Payments-Webhooks folgen der Spezifikation Standard Webhooks zur Überprüfung von Signaturen und zur Struktur von Payloads.

Key Features

Webhooks ermöglichen die Zustellung in Echtzeit mit integrierter Sicherheit, automatischen Wiederholungen und Ereignisfilterung. Alle offiziellen SDKs enthalten Hilfsfunktionen zur Signaturüberprüfung, und das Dashboard bietet Tools zum Testen, Überwachen und erneuten Abspielen.

Getting Started

1

Go to Developer → Webhooks

Navigieren Sie im Dodo Payments Dashboard zu Developer → Webhooks.
2

Click Add Endpoint

Klicken Sie auf Add endpoint, um einen neuen Webhook-Empfänger zu erstellen.
3

Enter Your Endpoint URL

Geben Sie die HTTPS-URL an, an die Dodo Payments Webhook-Ereignisse senden soll, oder wählen Sie einen Integrations-Connector (Slack, Discord, Zapier, Resend usw.), um Ereignisse ohne Code an einen Drittanbieterdienst weiterzuleiten.
4

Select Events

Wählen Sie die zu empfangenden Ereignisse aus. Ereignisse sind nach Ressource organisiert (payment, subscription, dispute usw.). Sie können einzelne Ereignisse oder eine gesamte Ressource auswählen, um alle zugehörigen Ereignisse zu empfangen.
5

Save

Klicken Sie auf Create endpoint. Ihr Webhook-Signaturgeheimnis wird im Tab Overview des Endpunkts angezeigt.
Bewahren Sie Ihr Webhook-Geheimnis sicher auf. Legen Sie es niemals in clientseitigem Code oder in der Versionsverwaltung offen.
Um Ihr Webhook-Geheimnis zu ändern, öffnen Sie den Endpunkt und klicken Sie neben dem Geheimnis im Tab Overview auf Rotate secret. Das alte Geheimnis bleibt nach der Änderung 24 Stunden lang gültig.

Integrations-Connectoren

Leiten Sie Webhook-Ereignisse mithilfe von Integrations-Connectoren direkt an Drittanbieterdienste weiter. Dadurch entfällt die Notwendigkeit, eigene Webhook-Handler zu entwickeln und zu warten.

Funktionsweise von Connectoren

Ein Connector wandelt Dodo Payments-Ereignisse in das vom Ziel erwartete Format um. Welche Angaben Sie machen müssen, hängt vom Ziel ab: Das Dashboard zeigt alle für Ihr Unternehmen verfügbaren Connectoren. Unter External Integrations erfahren Sie, was die einzelnen Ziele mit den Ereignissen tun können.

Einrichten eines Connectors

Beim Erstellen oder Bearbeiten eines Endpunkts wählen Sie einen Connector aus. Im Seitenbereich werden anschließend die Einrichtungsanweisungen für dieses Ziel angezeigt. Testen Sie die Umwandlung vor dem Speichern, um sicherzustellen, dass Ereignisse korrekt konvertiert werden.
Verwenden Sie einen Connector, um ein unterstütztes Ziel ohne Code zu erreichen. Wenn Sie benutzerdefinierte Logik benötigen, verwenden Sie stattdessen einen Standard-Endpunkt mit einer Transformation.

Konfigurieren abonnierter Ereignisse

Legen Sie fest, welche Ereignisse jeder Webhook-Endpunkt empfängt.
1

Navigate to Webhook Endpoints

Gehen Sie zu Developer → Webhooks und klicken Sie auf Ihren Endpunkt.
2

Open Event Configuration

Klicken Sie auf Edit, um den Seitenbereich für die Endpunktkonfiguration zu öffnen.
3

Select Events

Der Ereignistyp-Selektor zeigt alle verfügbaren Webhook-Ereignisse in einem durchsuchbaren, nach Ressource gruppierten Baum an (z. B. payment, subscription, dispute). Aktivieren Sie die Kontrollkästchen neben den Ereignissen, die Sie empfangen möchten. Sie können einzelne Ereignisse, eine gesamte Ressource oder eine beliebige Kombination auswählen.
4

Save Configuration

Klicken Sie auf Save, um Ihre Änderungen zu übernehmen.
Wenn Sie die Auswahl aller Ereignisse aufheben, empfängt Ihr Webhook-Endpunkt jeden Ereignistyp. Wählen Sie nur die Ereignisse aus, die Ihre Anwendung benötigt.

Ereigniskatalog

Gehen Sie zu Developer → Webhooks und öffnen Sie den Tab Event catalog, um jeden Ereignistyp zu sehen, den Dodo Payments senden kann. Wählen Sie ein Ereignis aus, um sein Schema und einen Beispiel-Payload anzuzeigen.

Webhook Events Guide

Durchsuchen Sie Ereignisse als Referenzdokumentation, gruppiert nach Ressource.

Webhook-Zustellung

Timeouts

Webhooks haben für Verbindungs- und Lesevorgänge jeweils ein 30-Sekunden-Timeout. Verarbeiten Sie Webhooks asynchron, indem Sie sofort einen 200-Statuscode zurückgeben und das Ereignis anschließend im Hintergrund verarbeiten.

Automatische Wiederholungen

Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff wiederholt, insgesamt bis zu 8-mal: Verwenden Sie das Dashboard, um fehlgeschlagene Nachrichten manuell erneut abzuspielen oder Nachrichten aus einem bestimmten Zeitraum gesammelt wiederherzustellen.

Idempotenz

Jeder Webhook enthält einen eindeutigen webhook-id-Header. Speichern Sie diese ID, um doppelte Ereignisse zu erkennen und zu überspringen, da Wiederholungen dasselbe Ereignis möglicherweise mehrfach zustellen.
Implementieren Sie immer Idempotenzprüfungen. Aufgrund von Wiederholungen erhalten Sie möglicherweise dasselbe Ereignis mehrfach.

Ereignisreihenfolge

Ereignisse können aufgrund von Wiederholungen oder Netzwerkbedingungen in falscher Reihenfolge eintreffen. Jeder Webhook enthält ein timestamp-Feld. Verwenden Sie es, um Ereignisse zu sortieren, falls Ihre Anwendung dies erfordert. Sie erhalten zum Zeitpunkt der Zustellung immer den aktuellsten Payload-Status.

Webhooks sichern

Validieren Sie Webhook-Payloads immer und verwenden Sie HTTPS.

Signaturen überprüfen

Jeder Webhook enthält einen webhook-signature-Header: eine HMAC-SHA256-Signatur des Payloads und Zeitstempels, die mit Ihrem geheimen Schlüssel signiert wurde.

SDK-Überprüfung (empfohlen)

Alle offiziellen SDKs enthalten integrierte Hilfsfunktionen. Setzen Sie DODO_PAYMENTS_WEBHOOK_KEY beim Initialisieren des Clients und rufen Sie anschließend unwrap() auf, um den Payload zu überprüfen und zu parsen. Es stehen zwei Methoden zur Verfügung:
  • unwrap — Überprüft die Signatur mit Ihrem Webhook-Geheimschlüssel und parst anschließend den Payload.
  • unsafe_unwrap — Parst den Payload, ohne ihn zu überprüfen. Verwenden Sie diese Methode nur für Tests.
Die Methodennamen folgen den Konventionen der jeweiligen Sprache: unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python und Unwrap / UnsafeUnwrap in Go.
Geben Sie Ihr Webhook-Geheimnis beim Initialisieren des Dodo Payments-Clients über DODO_PAYMENTS_WEBHOOK_KEY an.

Manuelle Überprüfung (Alternative)

Wenn Sie kein SDK verwenden, überprüfen Sie die Signatur selbst:
  1. Erstellen Sie den signierten Inhalt, indem Sie webhook-id, webhook-timestamp und den rohen Request-Body mit Punkten verbinden: {id}.{timestamp}.{body}. Verwenden Sie den rohen Body genau so, wie er empfangen wurde, bevor Sie ihn als JSON parsen.
  2. Nehmen Sie Ihr Webhook-Geheimnis. Wenn es mit whsec_ beginnt, entfernen Sie dieses Präfix und dekodieren Sie den Rest mit Base64, um den Signaturschlüssel zu erhalten.
  3. Berechnen Sie die HMAC-SHA256 des signierten Inhalts mit dem Signaturschlüssel und kodieren Sie das Ergebnis mit Base64.
  4. Der webhook-signature-Header enthält eine oder mehrere durch Leerzeichen getrennte Signaturen, jeweils im Format v1,<base64-signature>. Die Anfrage ist gültig, wenn eine beliebige v1-Signatur mit Ihrer übereinstimmt. Vergleichen Sie sie mit einer Funktion konstanter Laufzeit.
  5. Lehnen Sie die Anfrage ab, wenn webhook-timestamp zu stark von der aktuellen Zeit abweicht, um Replay-Angriffe zu verhindern. Die Standard-Webhooks-Bibliotheken erlauben 5 Minuten.
Unter Standard Webhooks libraries finden Sie Referenzimplementierungen. Informationen zu Event-Payload-Formaten finden Sie unter Webhook Payload.

Quell-IP-Adressen

Die Signaturüberprüfung ist die unterstützte Authentifizierungsmethode. Sie weist nach, dass die Anfrage mit Ihrem Webhook-Geheimnis signiert wurde – eine Prüfung auf Netzwerkebene kann dies nicht leisten. Webhook-Zustellungen stammen aus einem Pool von IP-Adressen, der sich im Laufe der Zeit ändert. Verlassen Sie sich bei der Authentifizierung nicht auf IP-Allowlists. Überprüfen Sie stattdessen immer den webhook-signature-Header, wie unter Signaturen überprüfen beschrieben. Wenn Ihre Firewall eine Allowlist erfordert:
  • Adressen nicht dauerhaft fest codieren. Bereiche ändern sich im Laufe der Zeit, und veraltete Regeln blockieren Zustellungen unbemerkt.
  • Fordern Sie die aktuellen Bereiche unter support@dodopayments.com an, bevor Sie eine Firewall einschränken.
  • Achten Sie auf Änderungsmitteilungen. Wenn sich Zustelladressen ändern, benachrichtigen wir betroffene Händler per E-Mail – übernehmen Sie die Aktualisierungen vor dem angegebenen Datum.
  • Lassen Sie die Signaturüberprüfung aktiviert, unabhängig von zusätzlichen Netzwerkregeln.
Auf serverlosen und verwalteten Hosting-Plattformen ist die Filterung eingehender IP-Adressen oft nicht verfügbar oder unpraktisch. Die Signaturüberprüfung ist in diesen Umgebungen die richtige Kontrolle.
Eine blockierte Zustellung gilt als Fehler und wird nach dem unter Automatische Wiederholungen beschriebenen Zeitplan wiederholt. Wenn Firewall-Regeln Zustellungen verhindert haben, können Sie sie nach der Behebung der Regeln erneut senden – siehe Nachrichten erneut abspielen und wiederherstellen.

Auf Webhooks antworten

Ihr Webhook-Handler muss einen 2xx status code zurückgeben, um den Empfang zu bestätigen. Jede andere Antwort gilt als Fehler, und der Webhook wird erneut zugestellt.

Best Practices

  • Nur HTTPS verwenden. HTTP-Endpunkte sind anfällig für Abfangen.
  • Sofort antworten. Geben Sie umgehend einen 200-Statuscode zurück und verarbeiten Sie das Ereignis anschließend asynchron.
  • Idempotenz implementieren. Verwenden Sie den webhook-id-Header, um doppelte Ereignisse zu erkennen und zu überspringen.
  • Ihr Geheimnis schützen. Speichern Sie DODO_PAYMENTS_WEBHOOK_KEY in Umgebungsvariablen oder einem Secrets Manager, niemals in der Versionsverwaltung.

Struktur des Webhook-Payloads

Anfrageformat

string
erforderlich
Eindeutiger Bezeichner für dieses Webhook-Ereignis. Wird für Idempotenzprüfungen verwendet.
string
erforderlich
HMAC-SHA256-Signatur zur Überprüfung der Authentizität des Webhooks.
string
erforderlich
Unix-Zeitstempel (in Sekunden), zu dem der Webhook gesendet wurde.

Request-Body

string
erforderlich
Ihre Geschäftskennung bei Dodo Payments.
string
erforderlich
Ereignistyp, der diesen Webhook ausgelöst hat (z. B. payment.succeeded, subscription.active).
string
erforderlich
Zeitstempel im ISO-8601-Format, zu dem das Ereignis aufgetreten ist.
object
erforderlich
Ereignisspezifischer Payload mit detaillierten Informationen zum Ereignis.

Beispiel-Payload

Event Types

Alle verfügbaren Webhook-Ereignistypen durchsuchen

Event Payloads

Detaillierte Payload-Schemas für jedes Ereignis anzeigen

Handle Payment Failures

Auf payment.failed reagieren und abgelehnte Zahlungen wiederherstellen

Webhooks testen

Beispielereignis senden

Testen Sie Ihre Webhook-Integration direkt über das Dashboard:
1

Navigate to Webhooks

Gehen Sie zu Developer → Webhooks und klicken Sie auf Ihren Endpunkt.
2

Open Testing Tab

Klicken Sie auf den Tab Testing.
3

Send Example

Wählen Sie einen Ereignistyp aus und klicken Sie auf Send example. Der Beispiel-Payload wird genau wie ein echtes Ereignis an Ihre Endpunkt-URL gesendet und auf dieselbe Weise signiert.
4

Check Your Endpoint

Bestätigen Sie, dass das Ereignis eingetroffen ist, die Signaturüberprüfung erfolgreich war und Sie einen 2xx-Statuscode zurückgegeben haben.
Fehlgeschlagene Nachrichten aus dem Tab Testing werden wie jeder andere Webhook nach dem normalen Wiederholungszeitplan erneut gesendet.

Implementierungsbeispiel

Vollständige Express.js-Implementierung mit Webhook-Überprüfung und -Verarbeitung:
Testen Sie Ihren Webhook-Handler gründlich über die Testoberfläche des Dashboards, bevor Sie Produktionsereignisse verarbeiten. So können Sie Probleme frühzeitig erkennen und beheben.

Webhooks mit der CLI testen

Die Dodo Payments CLI verfügt über zwei Befehle zum Testen von Webhooks während der lokalen Entwicklung.

Live-Webhooks lokal empfangen

Leiten Sie echte Webhook-Ereignisse von Ihrem Testmodus-Konto an Ihren lokalen Entwicklungsserver weiter:
Die CLI öffnet eine WebSocket-Verbindung und leitet jedes Webhook-Ereignis an Ihren lokalen Endpunkt weiter (z. B. http://localhost:3000/webhook), wobei alle Header für Tests der Signaturüberprüfung erhalten bleiben.
Der Listener funktioniert nur mit API-Schlüsseln im Testmodus. Führen Sie dodo login aus und wählen Sie zuerst den Test Mode.

Mock-Webhook-Ereignisse auslösen

Senden Sie Mock-Webhook-Payloads an einen beliebigen Endpunkt, ohne echte Transaktionen zu erstellen:
Mit diesem interaktiven Tool können Sie einen Ereignistyp auswählen und einen realistischen Mock-Payload an Ihren Endpunkt senden. Es läuft in einer Schleife, sodass Sie mehrere Ereignisse in einer Sitzung testen können. Der Trigger-Befehl umfasst die Familien für Abonnements, Zahlungen, Rückerstattungen, Disputes, Lizenzschlüssel, Auszahlungen, Gutschriften, abgebrochene Checkouts, Mahnverfahren und die Vergabe von Entitlements. Er sendet weder subscription.past_due noch subscription.unpaused. Eine genaue Liste finden Sie unter Supported Webhook Events.
Mock-Webhook-Payloads von dodo wh trigger sind nicht signiert. Verwenden Sie während des Testens ausschließlich die Methode zum ungeprüften Parsen (unsafeUnwrap in TypeScript, unsafe_unwrap in Python, UnsafeUnwrap in Go) in Ihrem Webhook-Handler.

CLI Webhook Testing Docs

Vollständige Dokumentation zum Testen von Webhooks mit der CLI anzeigen

Erweiterte Einstellungen

Der Tab Advanced bietet zusätzliche Konfigurationsoptionen zur Feinabstimmung des Verhaltens Ihres Webhook-Endpunkts.

Ratenbegrenzung (Drosselung)

Steuern Sie die Rate, mit der Webhook-Ereignisse an Ihren Endpunkt zugestellt werden. Standardmäßig gibt es für Webhooks keine Ratenbegrenzung, und Ereignisse werden zugestellt, sobald sie auftreten.
1

Open Advanced Tab

Klicken Sie auf der Detailseite Ihres Endpunkts auf den Tab Advanced.
2

Configure Rate Limit

Erweitern Sie den Bereich Endpoint throttling.
3

Set Your Limit

Geben Sie die maximale Anzahl von Nachrichten pro Sekunde ein und klicken Sie anschließend auf Save. Zustellungen über dieser Rate werden in eine Warteschlange eingereiht und nicht verworfen.

Benutzerdefinierte Header

Fügen Sie allen an Ihren Endpunkt gesendeten Webhook-Anfragen benutzerdefinierte HTTP-Header hinzu. Dies ist nützlich für Authentifizierung, Routing oder zusätzliche Metadaten.
1

Add Headers

Geben Sie im Bereich Custom headers einen Header-Namen und -Wert ein.
2

Add Multiple Headers

Klicken Sie für jeden weiteren Header auf Add header und anschließend auf Save.

Transformationen

Mit Transformationen können Sie den Payload eines Webhooks ändern und ihn optional an eine andere URL weiterleiten. Verwenden Sie Transformationen, um:
  • die Payload-Struktur vor der Verarbeitung zu ändern
  • Webhooks anhand ihres Inhalts an verschiedene Endpunkte weiterzuleiten
  • Felder zum Payload hinzuzufügen oder daraus zu entfernen
  • Datenformate zu transformieren
1

Enable Transformations

Aktivieren Sie im Bereich Transformation die Option Enable transformation.
2

Configure Transformation

Schreiben Sie Ihre Transformationsregeln im Code-Editor in JavaScript und klicken Sie anschließend auf Save. Der Code muss das Webhook-Objekt aus handler() zurückgeben.
3

Test Transformation

Verwenden Sie die Testoberfläche für Transformationen, um vor der Aktivierung zu überprüfen, ob Ihre Transformation korrekt funktioniert.
Transformationen können die Leistung der Webhook-Zustellung beeinflussen. Testen Sie gründlich und halten Sie die Transformationslogik einfach und effizient.

Webhook-Protokolle überwachen

Der Tab Logs bietet Einblick in den Status Ihrer Webhook-Zustellungen.
1

Navigate to Logs Tab

Gehen Sie zu Developer → Webhooks und öffnen Sie den Tab Logs.
2

Browse Delivery History

Zeigen Sie eine Tabelle mit allen Webhook-Zustellversuchen an, einschließlich der Spalten Event type, Message ID, Event ID, Sent at, Attempted at, Response code und Duration.
3

Search and Filter

Verwenden Sie die Suchleiste, um bestimmte Nachrichten nach ID oder Ereignistyp zu suchen. Filtern Sie nach Status (Succeeded, Failed, Pending usw.), um sich auf die zu untersuchenden Ereignisse zu konzentrieren.
4

View Message Details

Klicken Sie auf eine beliebige Nachricht, um die Nachrichtendetailseite zu öffnen. Diese zeigt:
  • den vollständigen Webhook-Payload
  • jeden Zustellversuch mit Antwortcode und Dauer
  • den Zeitstempel jedes Versuchs
  • alle Fehlermeldungen Ihres Endpunkts
Jeder Versuch verfügt über eine Aktion Replay, mit der Sie diese eine Nachricht erneut senden können, ohne die Seite zu verlassen.

Aktivitätsüberwachung

Gehen Sie zu Developer → Webhooks und öffnen Sie den Tab Activity, um die Zustellleistung über Ihre Endpunkte hinweg zu sehen. Delivery activity stellt Versuche im Zeitverlauf dar, gruppiert als Attempts per 5 minutes, Attempts per hour oder Attempts per day, abhängig vom Zeitraum. Jeder Balken ist nach Ergebnis aufgeteilt. Wenn Sie den Mauszeiger über ein Segment bewegen, werden Status, Anzahl der Versuche und dessen Anteil an der Gesamtsumme angezeigt. Bei einem Endpunkt fasst Delivery stats (last 24h) im Tab Overview dieselben Informationen für den vergangenen Tag zusammen.
Die Spalte Error rate (24h) im Tab Endpoints zeigt auf einen Blick, welche Endpunkte Aufmerksamkeit benötigen.

Nachrichten erneut abspielen und wiederherstellen

Wie Sie eine Nachricht erneut senden, hängt davon ab, wie viele Nachrichten betroffen sind:
  • Eine Nachricht — Öffnen Sie sie im Tab Logs und verwenden Sie die Aktion Replay für den Versuch.
  • Ein Nachrichtenbereich — Öffnen Sie den Endpunkt, da die Sammelmodi jeweils nur auf einen Endpunkt angewendet werden.

Sammelwiederholung

Öffnen Sie den Endpunkt über Developer → Webhooks. Es stehen drei Modi zur Verfügung, die jeweils nur auf diesen Endpunkt angewendet werden:
1

Open More Actions

Öffnen Sie am Endpunkt More actions und wählen Sie einen der drei oben genannten Modi aus.
2

Set the Range

Geben Sie den für den Modus erforderlichen Zeitraum ein, wie in der Tabelle aufgeführt.
3

Start the Run

Klicken Sie je nach ausgewähltem Modus auf Recover oder Replay.
Jeder Vorgang wird unter Replay history im Tab Overview des Endpunkts angezeigt, einschließlich Modus, Zeitraum, Status und Anzahl der erneut gesendeten Nachrichten.

E-Mail-Benachrichtigungen

Das Webhooks-Dashboard bietet keine E-Mail-Benachrichtigungen für fehlgeschlagene Zustellungen. Um Zustellungen zu überwachen, gehen Sie zu Developer → Webhooks und prüfen Sie die Tabs Logs und Activity.

Auf Cloud-Plattformen bereitstellen

Plattformspezifische Anleitungen zum Bereitstellen von Webhook-Handlern bei beliebten Cloud-Anbietern:

Vercel

Webhooks mit serverlosen Funktionen auf Vercel bereitstellen

Cloudflare Workers

Webhooks im Edge-Netzwerk von Cloudflare ausführen

Supabase Edge Functions

Webhooks mit Supabase integrieren

Netlify Functions

Webhooks als serverlose Netlify-Funktionen bereitstellen

Zugehörige API-Referenz

Create Webhook

Webhook-Endpunkte programmgesteuert erstellen und konfigurieren

List Webhooks

Ihre Webhook-Endpunkte abrufen und verwalten
Zuletzt geändert am 26. September 2026