Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
Das Webhooks-Portal von Dodo Payments wurde mit einer nativen Dashboard-Erfahrung neu aufgebaut. Ihre bestehenden Endpoints, Signaturgeheimnisse, Signaturüberprüfung, Ereignisnamen und Webhook-Nutzlasten bleiben unverändert. Es ist keine Integrationsarbeit erforderlich.
Wo sich die einzelnen Bereiche befinden.
Unter Developer → Webhooks — die Tabs Endpoints, Event catalog, Logs, Activity und Settings.
Auf einem einzelnen Endpoint — der Tab Overview mit Zustellungsstatistiken, dem Signaturgeheimnis und dem Replay history sowie den Tabs Testing und Advanced und den Aktionen für die Massenwiederholung.
Auf einer Nachricht — wird über den Tab Logs geöffnet. Dort kann jeder Zustellungsversuch einzeln wiederholt werden, ohne den Endpoint zu öffnen.
1
Access Webhook Settings
Navigieren Sie zum Dodo Payments Dashboard und gehen Sie zu Developer → Webhooks.
2
Create Webhook Endpoint
Klicken Sie auf Add endpoint, um das seitliche Fenster zur Endpoint-Erstellung zu öffnen.
3
Enter Endpoint URL or Choose Integration
Geben Sie die URL ein, unter der Sie Webhook-Ereignisse empfangen möchten, oder wählen Sie einen Integrations-Connector aus, um Ereignisse an einen Drittanbieterdienst (Slack, Discord, Zapier, Resend usw.) weiterzuleiten.
4
Select Events to Receive
Wählen Sie die spezifischen Ereignisse aus, auf die Ihr Endpoint reagieren soll. Die Ereignisse sind in einem durchsuchbaren, nach Ressourcen gruppierten Baum organisiert. Sie können einzelne Ereignisse oder eine übergeordnete Ressource auswählen, um alle zugehörigen Ereignisse zu empfangen.
Nur ausgewählte Ereignisse lösen Webhooks an Ihren Endpoint aus. So vermeiden Sie unnötigen Datenverkehr und unnötige Verarbeitung.
5
Create Endpoint
Klicken Sie auf Create endpoint, um Ihre Konfiguration zu speichern.
6
Get Secret Key
Ihr Webhook-Signaturgeheimnis wird im Tab Overview des Endpoints angezeigt. Sie verwenden es, um die Authentizität empfangener Webhooks zu überprüfen.
Bewahren Sie Ihren Webhook-Geheimschlüssel sicher auf und legen Sie ihn niemals in clientseitigem Code oder öffentlichen Repositories offen.
7
Rotate Secret (Optional)
Bei Bedarf können Sie Ihr Webhook-Geheimnis für zusätzliche Sicherheit rotieren. Klicken Sie im Tab Overview neben dem Geheimnis auf Rotate secret.
Durch die Rotation läuft das Geheimnis ab und wird durch ein neues ersetzt. Das alte Geheimnis bleibt nur für die nächsten 24 Stunden gültig. Danach schlägt eine Überprüfung mit dem alten Geheimnis fehl.
Rotieren Sie das Geheimnis regelmäßig oder sofort, wenn Sie vermuten, dass Ihr aktuelles Geheimnis kompromittiert wurde.
Anstatt einen eigenen Webhook-Empfänger zu erstellen, können Sie Webhook-Ereignisse mithilfe von Integrations-Connectoren direkt an Drittanbieterdienste weiterleiten. Dadurch müssen Sie keine benutzerdefinierten Webhook-Handler für gängige Plattformen schreiben und warten.
Ein Connector enthält eine Transformation, die das Dodo Payments-Ereignis in die von der Zielanwendung erwartete Form umwandelt. Welche Angaben Sie machen müssen, hängt vom Ziel ab:
Connector-Typ
Ihre Angaben
Ziele
Incoming webhook URL
Eine Webhook-URL, die Sie im eigenen Dashboard des Anbieters erstellen. Kein API key.
Die Connector-Auswahl im Dashboard zeigt die vollständige Liste, die derzeit für Ihr Unternehmen verfügbar ist. Betrachten Sie die obige Tabelle daher als Liste der Ziele mit Schritt-für-Schritt-Anleitungen und nicht als vollständige Aufstellung. Unter External Integrations erfahren Sie, welche Funktionen die einzelnen Ziele bieten, sobald sie Ereignisse empfangen.
Wählen Sie beim Erstellen oder Bearbeiten eines Endpoints einen Connector aus. Das seitliche Fenster zeigt dann für das jeweilige Ziel verfasste Einrichtungsanweisungen an – beispielsweise zum Erstellen einer eingehenden Webhook-URL in Slack oder zum Auffinden Ihres Resend API key. Führen Sie vor dem Speichern den Test der Connector-Transformation aus, um zu bestätigen, dass das Ereignis korrekt für das Ziel umgewandelt wird.
Verwenden Sie einen Connector, um ein unterstütztes Ziel ohne eigenen Code zu erreichen. Wenn Sie benutzerdefinierte Logik benötigen, verwenden Sie stattdessen einen Standard-Endpoint mit einer Transformation.
Sie können konfigurieren, welche spezifischen Ereignisse jeder Webhook-Endpoint empfangen soll.
1
Navigate to Webhook Endpoints
Gehen Sie zu Ihrem Dodo Payments Dashboard und navigieren Sie zu Developer → Webhooks.
2
Select Your Endpoint
Klicken Sie auf den Webhook-Endpoint, den Sie konfigurieren möchten.
3
Open Event Configuration
Klicken Sie auf Edit, um das seitliche Fenster zur Endpoint-Konfiguration zu öffnen.
4
Browse Event Types
Die Auswahl des Ereignistyps zeigt alle verfügbaren Webhook-Ereignisse in einem durchsuchbaren, nach Ressourcen gruppierten Baum an (z. B. payment, subscription, dispute). Verwenden Sie die Suchleiste, um bestimmte Ereignisse schnell anhand ihres Namens oder eines Schlüsselworts zu finden.
5
Select Events
Aktivieren Sie die Kontrollkästchen neben den Ereignissen, die Sie empfangen möchten. Sie können:
einzelne Ereignisse auswählen (z. B. payment.succeeded, payment.failed)
eine übergeordnete Ressource auswählen, um alle zugehörigen Ereignisse zu empfangen
spezifische Ereignisse entsprechend Ihren Anforderungen kombinieren
6
Save Configuration
Klicken Sie auf Save, um Ihre Änderungen anzuwenden, oder auf Cancel, um die Änderungen zu verwerfen.
Wenn Sie alle Ereignisse abwählen, empfängt Ihr Webhook-Endpoint keine Benachrichtigungen. Wählen Sie mindestens die Ereignisse aus, die Ihre Anwendung für den ordnungsgemäßen Betrieb benötigt.
Gehen Sie zu Developer → Webhooks und öffnen Sie den Tab Event catalog. Dort sind alle Ereignistypen aufgeführt, die Dodo Payments senden kann. So sehen Sie, welche Ereignisse verfügbar sind, bevor Sie einen Endpoint dafür abonnieren. Wählen Sie ein Ereignis aus, um sein Schema und eine Beispielnutzlast anzuzeigen. Dies ist der schnellste Weg, die Struktur eines Feldes zu überprüfen, das Sie auslesen möchten.
Webhook Events Guide
Durchsuchen Sie dieselben Ereignisse als Referenzdokumentation, gruppiert nach Ressource.
Für Webhooks gilt sowohl für Verbindungs- als auch für Lesevorgänge ein 15-sekündiges Timeout-Fenster. Stellen Sie sicher, dass Ihr Endpoint schnell antwortet, um Timeouts zu vermeiden.
Verarbeiten Sie Webhooks asynchron, indem Sie den Empfang sofort mit einem 200 status code bestätigen und die eigentliche Verarbeitung anschließend im Hintergrund durchführen.
Wenn eine Webhook-Zustellung fehlschlägt, führt Dodo Payments automatisch Wiederholungen mit exponentiellem Backoff durch, um eine Überlastung Ihres Systems zu verhindern.
Versuch
Verzögerung
Beschreibung
1
Sofort
Der erste Wiederholungsversuch erfolgt unmittelbar
2
5 Sekunden
Der zweite Versuch erfolgt nach einer kurzen Verzögerung
3
5 Minuten
Der dritte Versuch erfolgt mit erhöhtem Backoff
4
30 Minuten
Der vierte Versuch setzt den Backoff fort
5
2 Stunden
Der fünfte Versuch erfolgt mit verlängerter Verzögerung
6
5 Stunden
Der sechste Versuch erfolgt mit längerer Verzögerung
7
10 Stunden
Der siebte Versuch erfolgt mit maximaler Verzögerung
8
10 Stunden
Letzter Versuch – der Webhook wird bei einem Fehlschlag als fehlgeschlagen markiert
Maximal 8 Wiederholungsversuche pro Webhook-Ereignis. Wenn ein Webhook beispielsweise dreimal fehlschlägt, bevor er erfolgreich zugestellt wird, beträgt die gesamte Zustellungszeit ab dem ersten Versuch ungefähr 35 Minuten und 5 Sekunden.
Verwenden Sie das Dodo Payments Dashboard, um einzelne Nachrichten manuell zu wiederholen oder jederzeit alle fehlgeschlagenen Nachrichten gesammelt wiederherzustellen.
Jedes Webhook-Ereignis enthält einen eindeutigen webhook-id header. Verwenden Sie diesen Identifier, um Idempotenz zu implementieren und eine doppelte Verarbeitung zu verhindern.
// Example: Storing webhook IDs to prevent duplicate processingconst processedWebhooks = new Set();app.post('/webhook', (req, res) => { const webhookId = req.headers['webhook-id']; if (processedWebhooks.has(webhookId)) { return res.status(200).json({ received: true }); } processedWebhooks.add(webhookId); // Process the webhook...});
Implementieren Sie immer Idempotenzprüfungen. Aufgrund von Wiederholungen kann dasselbe Ereignis mehrfach bei Ihnen eingehen.
Webhook-Ereignisse können aufgrund von Wiederholungen oder Netzwerkbedingungen in einer anderen Reihenfolge eintreffen. Entwickeln Sie Ihr System so, dass es Ereignisse in beliebiger Reihenfolge verarbeiten kann.
Sie erhalten die zum Zeitpunkt der Zustellung aktuellste Nutzlast, unabhängig davon, wann das Webhook-Ereignis ursprünglich ausgelöst wurde.
Jede Webhook-Anfrage enthält einen webhook-signature header, eine HMAC-SHA256-Signatur der Webhook-Nutzlast und des Zeitstempels, die mit Ihrem Geheimschlüssel signiert wurde.
Alle offiziellen SDKs enthalten integrierte Hilfsfunktionen, um eingehende Webhooks sicher zu validieren und zu parsen. Es stehen zwei Methoden zur Verfügung:
unwrap(): Überprüft Signaturen mithilfe Ihres Webhook-Geheimschlüssels
unsafe_unwrap(): Parst Nutzlasten ohne Überprüfung
Geben Sie Ihr Webhook-Geheimnis über DODO_PAYMENTS_WEBHOOK_KEY an, wenn Sie den Dodo Payments-Client initialisieren.
Wenn Sie kein SDK verwenden, können Sie Signaturen selbst gemäß der Standard-Webhooks-Spezifikation überprüfen:
Erstellen Sie die signierte Nachricht, indem Sie webhook-id, webhook-timestamp und die exakt als Zeichenfolge serialisierte payload durch Punkte (.) getrennt verketten.
Berechnen Sie den HMAC SHA256 dieser Zeichenfolge mithilfe Ihres Webhook-Geheimschlüssels aus dem Dashboard.
Vergleichen Sie die berechnete Signatur mit dem webhook-signature header. Stimmen sie überein, ist der Webhook authentisch.
Die Signaturüberprüfung ist die unterstützte Methode zur Authentifizierung eines Webhooks. Sie weist nach, dass die Anfrage mit deinem Webhook-Secret signiert wurde – eine Prüfung auf Netzwerkebene kann dies nicht leisten.Webhook-Zustellungen werden aus einem Pool von Quell-IP-Adressen gesendet, die zu unserer Zustellungsinfrastruktur gehören. Dieser Pool ändert sich von Zeit zu Zeit. Behandle die Adressen daher als betriebliche Details und nicht als feste Eigenschaft der Integration.
Verwende keine Quell-IP-Allowlist als Authentifizierungsmechanismus. Eine Allowlist zeigt nur, woher eine Anfrage stammt, nicht, ob sie echt oder unverändert ist – überprüfe den webhook-signature-Header bei jeder Anfrage, wie unter Signaturen überprüfen beschrieben.
Wenn deine Infrastruktur hinter einer Firewall liegt, die eine explizite Allowlist erfordert, beachte Folgendes:
Adressen nicht dauerhaft fest codieren. Bereiche werden im Laufe der Zeit hinzugefügt und entfernt, und eine veraltete Regel blockiert Zustellungen unbemerkt.
Fordere die aktuellen Bereiche unter support@dodopayments.com an, bevor du eine Firewall einschränkst, damit du mit einer aktuellen Liste arbeitest.
Achte auf Änderungsmitteilungen. Wenn sich Zustellungsadressen ändern, benachrichtigen wir betroffene Händler per E-Mail – übernimm diese Aktualisierungen vor dem angegebenen Datum, um ausbleibende Zustellungen zu vermeiden.
Lasse die Signaturüberprüfung aktiviert, unabhängig von den zusätzlich eingerichteten Netzwerkregeln.
Auf serverlosen und verwalteten Hosting-Plattformen ist die Filterung eingehender IPs oft nicht verfügbar oder nur schwer zu warten. Die Signaturüberprüfung ist in diesen Umgebungen die richtige Kontrolle, und es ist keine Allowlist erforderlich.
Eine blockierte Zustellung wird wie jeder andere Fehler behandelt und nach dem unter Automatische Retries beschriebenen Zeitplan erneut versucht. Wenn Firewall-Regeln zu fehlgeschlagenen Zustellungen geführt haben, kannst du sie nach der Behebung der Regeln erneut senden – siehe Nachrichten wiedergeben und wiederherstellen.
Du kannst deine Webhook-Integration direkt über das Dodo Payments Dashboard testen, um sicherzustellen, dass dein Endpunkt vor dem Livegang korrekt funktioniert.
1
Navigate to Webhooks
Öffne dein Dodo Payments Dashboard und navigiere zu Developer → Webhooks.
2
Select Your Endpoint
Klicke auf deinen Webhook-Endpunkt, um seine Detailseite zu öffnen.
3
Open Testing Tab
Klicke auf den Tab Testing, um die Webhook-Testoberfläche zu öffnen.
Der Tab Testing sendet eine Beispiel-Payload an diesen Endpunkt, damit du deinen Empfänger überprüfen kannst.
1
Select Event Type
Verwende Select an event type, um das zu testende Event auszuwählen, zum Beispiel payment.succeeded oder payment.failed.
2
Send Example
Klicke auf Send example. Die Beispiel-Payload wird genau wie ein echtes Event an deine Endpunkt-URL gesendet und auf dieselbe Weise signiert.
Fehlgeschlagene Nachrichten aus dem Tab Testing werden nicht erneut versucht. Verwende ihn zur Überprüfung deines Empfängers, nicht zum Testen des Retry-Zeitplans.
3
Check Your Endpoint
Der Tab protokolliert, wann Last example sent gesendet wurde. Bestätige, dass das Event angekommen ist, die Signaturüberprüfung erfolgreich war und du einen 2xx-Statuscode zurückgegeben hast.
Teste deinen Webhook-Handler gründlich über die Dashboard-Testoberfläche, bevor du Produktions-Events verarbeitest. So kannst du Probleme frühzeitig erkennen und beheben.
Leite echte Webhook-Events von deinem Testmodus-Konto in Echtzeit an deinen lokalen Entwicklungsserver weiter:
dodo wh listen
Die CLI öffnet eine WebSocket-Verbindung zu Dodo Payments und leitet jedes Webhook-Event an deinen lokalen Endpunkt weiter (z. B. http://localhost:3000/webhook). Dabei bleiben alle Headers einschließlich der Signatur-Header für Tests der Überprüfung erhalten.
Der Listener funktioniert nur mit API-Keys im test mode. Führe dodo login aus und wähle vor der Verwendung dieses Befehls den Test Mode.
Sende Mock-Webhook-Payloads an beliebige Endpunkte, ohne echte Transaktionen zu erstellen:
dodo wh trigger
Mit diesem interaktiven Tool kannst du einen Eventtyp auswählen und eine realistische Mock-Payload an deinen Endpunkt senden. Das Tool läuft in einer Schleife, sodass du mehrere Events in einer Sitzung testen kannst.Der Trigger-Befehl deckt alle 47 Eventtypen ab, die Dodo Payments zustellt, einschließlich der Gruppen für Subscription, Zahlung, Rückerstattung, Dispute, Lizenzschlüssel, Auszahlung, Guthaben, abgebrochenen Checkout, Dunning und Entitlement Grant – die vollständige Liste findest du unter Unterstützte Webhook-Events.
Mock-Webhook-Payloads aus dodo wh trigger sind nicht signiert. Verwende während des Testens ausschließlich unsafe_unwrap() anstelle von unwrap() in deinem Webhook-Handler.
CLI Webhook Testing Docs
Siehe die vollständige Dokumentation zum Testen von Webhooks mit der CLI
Füge allen an deinen Endpunkt gesendeten Webhook-Anfragen benutzerdefinierte HTTP-Headers hinzu. Dies ist nützlich für Authentifizierung, Routing oder das Hinzufügen von Metadaten.
1
Add Headers
Gib im Abschnitt “Custom Headers” für jeden benutzerdefinierten Header einen Key und einen Value ein.
2
Add Multiple Headers
Klicke auf die Schaltfläche +, um bei Bedarf weitere benutzerdefinierte Headers hinzuzufügen.
Deine benutzerdefinierten Headers werden in alle Webhook-Anfragen an diesen Endpunkt aufgenommen.
Mit Transformationen kannst du die Payload eines Webhooks ändern und ihn optional an eine andere URL weiterleiten. Diese leistungsstarke Funktion ermöglicht Folgendes:
Die Payload-Struktur vor der Verarbeitung ändern
Webhooks anhand ihres Inhalts an verschiedene Endpunkte weiterleiten
Felder zur Payload hinzufügen oder daraus entfernen
Datenformate transformieren
1
Enable Transformations
Aktiviere den Schalter Enabled, um die Transformationsfunktion einzuschalten.
2
Configure Transformation
Klicke auf Edit transformation, um deine Transformationsregeln mit JavaScript zu definieren.
3
Test Transformation
Verwende die Testoberfläche für Transformationen, um vor dem Livegang zu überprüfen, ob deine Transformation korrekt funktioniert.
Transformationen können die Zustellungsleistung von Webhooks beeinflussen. Teste sie gründlich und halte die Transformationslogik einfach und effizient.
Transformationen sind besonders nützlich für:
Die Konvertierung zwischen verschiedenen Datenformaten
Das Filtern von Events anhand bestimmter Kriterien
Das Hinzufügen berechneter Felder zur Payload
Das Weiterleiten von Events an verschiedene Microservices
Der Tab Logs bietet umfassende Einblicke in den Status deiner Webhook-Zustellungen und ermöglicht dir, Webhook-Events effektiv zu überwachen, zu debuggen und zu verwalten.
1
Navigate to Logs Tab
Öffne Developer → Webhooks und anschließend den Tab Logs.
2
Browse Delivery History
Zeige eine Tabelle mit allen Zustellungsversuchen von Webhooks an. Die Spalten enthalten Event type, Message ID, Event ID, Sent at, Attempted at, Response code und Duration.
3
Search and Filter
Verwende die Suchleiste, um bestimmte Nachrichten anhand ihrer ID oder ihres Eventtyps zu finden. Filtere nach Status (Succeeded, Failed, Pending usw.), um dich auf die zu untersuchenden Events zu konzentrieren.
4
View Message Details
Klicke auf eine beliebige Nachricht, um die Nachrichtendetailseite zu öffnen. Dort werden Folgendes angezeigt:
Die vollständige Webhook-Payload
Jeder Zustellungsversuch mit Response Code und Dauer
Der Zeitstempel jedes Versuchs
Alle Fehlermeldungen deines Endpunkts
Jeder Versuch enthält die Aktion Replay, sodass du diese eine Nachricht erneut zustellen kannst, ohne die Seite zu verlassen.
Öffne Developer → Webhooks und anschließend den Tab Activity, um die Zustellungsleistung über alle deine Endpunkte hinweg anzuzeigen.Delivery activity stellt Versuche im Zeitverlauf dar, gruppiert als Attempts per 5 minutes, Attempts per hour oder Attempts per day, abhängig vom Zeitfenster. Jeder Balken ist nach Ergebnis aufgeteilt. Wenn du den Mauszeiger über ein Segment bewegst, werden der Status, die Anzahl der Versuche und deren 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 dir auf einen Blick, welche Endpunkte Aufmerksamkeit benötigen, bevor du einen davon öffnest.
Öffne den Endpunkt über Developer → Webhooks. Es sind drei Modi verfügbar, die jeweils nur auf diesen Endpunkt angewendet werden. Der festgelegte Bereich hängt vom Modus ab:
Modus
Funktion
Festzulegende Werte
Recover failed messages
Gibt jede an diesen Endpunkt gesendete und fehlgeschlagene Nachricht erneut wieder.
Ein Startpunkt: 8 hours ago, Yesterday, 3 days ago, Last week oder 2 weeks ago
Replay missing messages
Gibt Nachrichten erneut wieder, die nie an diesen Endpunkt gesendet wurden, zum Beispiel nachdem du ihn für einen neuen Eventtyp abonniert hast.
Dieselben Startpunkte
Bulk replay messages
Gibt Nachrichten erneut wieder, die den ausgewählten Filtern entsprechen, einschließlich bereits erfolgreich zugestellter Nachrichten.
Begrenzungen für Since und Until, standardmäßig für die letzten zwei Wochen, sowie optionale Eventtypen, Channels oder Tags
1
Open More Actions
Öffne am Endpunkt More actions und wähle einen der drei oben genannten Modi aus.
2
Set the Range
Gib den von diesem Modus geforderten Bereich wie in der Tabelle angegeben ein.
3
Start the Run
Klicke je nach ausgewähltem Modus auf Recover oder Replay.
Jeder Durchlauf erscheint unter Replay history im Tab Overview des Endpunkts, einschließlich Modus, Zeitraum, Status und Anzahl der erneut gesendeten Nachrichten.
Erhalte eine E-Mail-Benachrichtigung, wenn Webhook-Zustellungen an einen Endpunkt fehlschlagen, damit du Probleme beheben kannst, bevor sie sich zu einem Rückstau entwickeln.
1
Navigate to Settings Tab
Öffne Developer → Webhooks und anschließend den Tab Settings.
2
Find Email Alerting
Suche die Karte Email alerting.
3
Configure Email Addresses
Gib die Adressen ein, die die Benachrichtigungen erhalten sollen. Trenne mehrere Adressen durch Kommas. Lasse das Feld leer, um Benachrichtigungen zu deaktivieren.
4
Save
Klicke auf Save, um deine Änderungen zu übernehmen.
Aktiviere E-Mail-Benachrichtigungen, um Probleme bei Webhook-Zustellungen frühzeitig zu erkennen und zuverlässige Integrationen aufrechtzuerhalten.
Bereit, deinen Webhook-Handler in der Produktion bereitzustellen? Wir bieten plattformspezifische Anleitungen für die Bereitstellung von Webhooks bei beliebten Cloud-Anbietern, einschließlich Best Practices für jede Plattform.
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
Jede Plattformanleitung enthält die Umgebungseinrichtung, die Signaturüberprüfung und die für den jeweiligen Anbieter spezifischen Bereitstellungsschritte.