
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
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
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: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.Konfigurieren abonnierter Ereignisse
Legen Sie fest, welche Ereignisse jeder Webhook-Endpunkt empfängt.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
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.Save Configuration
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
Webhook-Zustellung
Timeouts
Webhooks haben für Verbindungs- und Lesevorgänge jeweils ein 30-Sekunden-Timeout. Verarbeiten Sie Webhooks asynchron, indem Sie sofort einen200-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:Idempotenz
Jeder Webhook enthält einen eindeutigenwebhook-id-Header. Speichern Sie diese ID, um doppelte Ereignisse zu erkennen und zu überspringen, da Wiederholungen dasselbe Ereignis möglicherweise mehrfach zustellen.
Ereignisreihenfolge
Ereignisse können aufgrund von Wiederholungen oder Netzwerkbedingungen in falscher Reihenfolge eintreffen. Jeder Webhook enthält eintimestamp-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 einenwebhook-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 SieDODO_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.
unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python und Unwrap / UnsafeUnwrap in Go.
Manuelle Überprüfung (Alternative)
Wenn Sie kein SDK verwenden, überprüfen Sie die Signatur selbst:- Erstellen Sie den signierten Inhalt, indem Sie
webhook-id,webhook-timestampund 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. - 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. - Berechnen Sie die HMAC-SHA256 des signierten Inhalts mit dem Signaturschlüssel und kodieren Sie das Ergebnis mit Base64.
- Der
webhook-signature-Header enthält eine oder mehrere durch Leerzeichen getrennte Signaturen, jeweils im Formatv1,<base64-signature>. Die Anfrage ist gültig, wenn eine beliebigev1-Signatur mit Ihrer übereinstimmt. Vergleichen Sie sie mit einer Funktion konstanter Laufzeit. - Lehnen Sie die Anfrage ab, wenn
webhook-timestampzu stark von der aktuellen Zeit abweicht, um Replay-Angriffe zu verhindern. Die Standard-Webhooks-Bibliotheken erlauben 5 Minuten.
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 denwebhook-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 Webhooks antworten
Ihr Webhook-Handler muss einen2xx 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_KEYin Umgebungsvariablen oder einem Secrets Manager, niemals in der Versionsverwaltung.
Struktur des Webhook-Payloads
Anfrageformat
Header
Request-Body
payment.succeeded, subscription.active).Beispiel-Payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed reagieren und abgelehnte Zahlungen wiederherstellenWebhooks testen
Beispielereignis senden
Testen Sie Ihre Webhook-Integration direkt über das Dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx-Statuscode zurückgegeben haben.Implementierungsbeispiel
Vollständige Express.js-Implementierung mit Webhook-Überprüfung und -Verarbeitung: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:http://localhost:3000/webhook), wobei alle Header für Tests der Signaturüberprüfung erhalten bleiben.
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:subscription.past_due noch subscription.unpaused. Eine genaue Liste finden Sie unter Supported Webhook Events.
CLI Webhook Testing Docs
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.Open Advanced Tab
Configure Rate Limit
Set Your Limit
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.Add Headers
Add Multiple Headers
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
Enable Transformations
Configure Transformation
handler() zurückgeben.Test Transformation
Webhook-Protokolle überwachen
Der Tab Logs bietet Einblick in den Status Ihrer Webhook-Zustellungen.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- den vollständigen Webhook-Payload
- jeden Zustellversuch mit Antwortcode und Dauer
- den Zeitstempel jedes Versuchs
- alle Fehlermeldungen Ihres Endpunkts
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.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:Open More Actions
Set the Range
Start the Run