
Unsere Webhook-Implementierung folgt der Standard Webhooks Spezifikation, wodurch die Kompatibilität mit branchenüblichen Best Practices und bestehenden Webhook-Bibliotheken gewährleistet ist.
Hauptmerkmale
Real-time Delivery
Erhalten Sie sofortige Benachrichtigungen, sobald Ereignisse auftreten
Secure by Default
Inklusive HMAC-SHA256-Signaturprüfung
Automatic Retries
Eingebaute Wiederholungslogik mit exponentiellem Backoff
Event Filtering
Abonnieren Sie nur die Ereignisse, die Sie tatsächlich benötigen
Erste Schritte
Access Webhook Settings
Navigieren Sie zum DodoPayments-Dashboard und gehen Sie zu
Settings > Webhooks.Select Events to Receive
Wählen Sie die spezifischen Ereignisse aus, auf die Ihr Webhook-Endpunkt reagieren soll, indem Sie sie in der Ereignisliste markieren.
Get Secret Key
Besorgen Sie sich Ihr Webhook
Secret Key auf der Einstellungsseite. Sie benötigen diesen zur Überprüfung der Authentizität empfangener Webhooks.Rotate Secret (Optional)
Falls erforderlich, können Sie Ihren Webhook-Geheimschlüssel zur Erhöhung der Sicherheit rotieren. Klicken Sie in den Webhook-Einstellungen auf die Rotate Secret-Schaltfläche.
Rotieren Sie den Geheimschlüssel regelmäßig oder sofort, wenn Sie vermuten, dass er kompromittiert wurde.
Abonnierte Ereignisse konfigurieren
Sie können konfigurieren, welche spezifischen Ereignisse sie für jeden Webhook-Endpunkt empfangen möchten.Zugriff auf die Ereigniskonfiguration
Navigate to Webhook Details
Gehen Sie zum Dodo Payments Dashboard und navigieren Sie zu
Settings > Webhooks.Ereignisabonnements verwalten
View Available Events
Die Oberfläche zeigt alle verfügbaren Webhook-Ereignisse in einer hierarchischen Struktur. Ereignisse sind nach Kategorien gruppiert (z. B.
dispute, payment, subscription).Search and Filter
Verwenden Sie die Suchleiste, um bestimmte Ereignisse schnell zu finden, indem Sie Ereignisnamen oder Schlüsselwörter eingeben.
Select Events
Aktivieren Sie die Kontrollkästchen neben den Ereignissen, die Sie erhalten möchten. Sie können:
- Einzelne Unterereignisse auswählen (z. B.
dispute.accepted,dispute.challenged) - Oberereignisse auswählen, um alle zugehörigen Unterereignisse zu erhalten
- Bestimmte Ereignisse je nach Bedarf kombinieren
Review Event Details
Führen Sie den Mauszeiger über das Informationssymbol (ⓘ) neben jedem Ereignis, um eine Beschreibung zu sehen, wann dieses Ereignis ausgelöst wird.
Webhook-Lieferung
Zeitüberschreitungen
Webhooks haben ein 15-Sekunden-Zeitüberschreitungsfenster für sowohl Verbindungs- als auch Lesevorgänge. Stellen Sie sicher, dass Ihr Endpunkt schnell reagiert, um Zeitüberschreitungen zu vermeiden.Automatische Wiederholungen
Wenn die Lieferung eines Webhooks fehlschlägt, versucht Dodo Payments automatisch mit exponentiellem Backoff, um zu verhindern, dass Ihr System überlastet wird.| Versuch | Verzögerung | Beschreibung |
|---|---|---|
| 1 | Sofort | Der erste Versuch erfolgt sofort |
| 2 | 5 Sekunden | Der zweite Versuch nach kurzer Verzögerung |
| 3 | 5 Minuten | Der dritte Versuch mit erhöhtem Backoff |
| 4 | 30 Minuten | Der vierte Versuch mit fortgesetztem Backoff |
| 5 | 2 Stunden | Der fünfte Versuch mit verlängerter Verzögerung |
| 6 | 5 Stunden | Der sechste Versuch mit längerer Verzögerung |
| 7 | 10 Stunden | Der siebte Versuch mit maximaler Verzögerung |
| 8 | 10 Stunden | Letzter Versuch - Webhook wird als fehlgeschlagen markiert, wenn er nicht erfolgreich ist |
Maximal 8 Wiederholungsversuche pro Webhook-Ereignis. Wenn ein Webhook beispielsweise dreimal fehlschlägt, bevor er erfolgreich zugestellt wird, beträgt die gesamte Lieferzeit ab dem ersten Versuch etwa 35 Minuten und 5 Sekunden.
Idempotenz
Jedes Webhook-Ereignis enthält einen einzigartigenwebhook-id-Header. Verwenden Sie diesen Bezeichner, um Idempotenz zu implementieren und doppelte Verarbeitung zu vermeiden.
Ereignisreihenfolge
Webhook-Ereignisse können aufgrund von Wiederholungen oder Netzwerkbedingungen in einer anderen Reihenfolge ankommen. Gestalten Sie Ihr System so, dass es Ereignisse in beliebiger Reihenfolge verarbeiten kann.Sie erhalten die aktuelle Nutzlast zum Zeitpunkt der Zustellung, unabhängig davon, wann das Webhook-Ereignis ursprünglich ausgelöst wurde.
Webhooks sichern
Um die Sicherheit Ihrer Webhooks zu gewährleisten, validieren Sie immer die Nutzlasten und verwenden Sie HTTPS.Signaturen überprüfen
Jede Webhook-Anfrage enthält einenwebhook-signature-Header, eine HMAC-SHA256-Signatur der Webhook-Nutzlast und des Zeitstempels, signiert mit Ihrem Geheimschlüssel.
SDK-Überprüfung (empfohlen)
Alle offiziellen SDKs enthalten integrierte Hilfsfunktionen zur sicheren Validierung und Analyse eingehender Webhooks. Es stehen zwei Methoden zur Verfügung:unwrap(): Überprüft Signaturen mithilfe Ihres Webhook-Geheimschlüsselsunsafe_unwrap(): Analysiert Nutzlasten ohne Verifizierung
Manuelle Überprüfung (Alternative)
Wenn Sie kein SDK verwenden, können Sie Signaturen selbst überprüfen, indem Sie der Standard-Webhooks-Spezifikation folgen:- Erstellen Sie die signierte Nachricht, indem Sie
webhook-id,webhook-timestampund den exakten, rohen, in einen String umgewandeltenpayloadmit Punkten (.) trennen und aneinanderreihen. - Berechnen Sie die HMAC-SHA256 dieses Strings mithilfe Ihres Webhook-Geheimschlüssels vom Dashboard.
- Vergleichen Sie die berechnete Signatur mit dem
webhook-signature-Header. Stimmen sie überein, ist der Webhook authentisch.
Wir folgen der Standard Webhooks Spezifikation. Sie können deren Bibliotheken zur Signaturverifizierung verwenden: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Informationen zu Ereignis-Payload-Formaten finden Sie unter Webhook Payload.
Auf Webhooks reagieren
- Ihr Webhook-Handler muss einen
2xx status codezurückgeben, um den Empfang des Ereignisses zu bestätigen. - Jede andere Antwort wird als Fehler behandelt und der Webhook wird erneut gesendet.
Beste Praktiken
Use HTTPS endpoints only
Use HTTPS endpoints only
Verwenden Sie stets HTTPS-URLs für Webhook-Endpunkte. HTTP-Endpunkte sind anfällig für Man-in-the-Middle-Angriffe und setzen Ihre Webhook-Daten einem Risiko aus.
Respond immediately
Respond immediately
Geben Sie sofort beim Empfang des Webhooks einen
200-Statuscode zurück. Verarbeiten Sie das Ereignis asynchron, um Timeouts zu vermeiden.Handle duplicate events
Handle duplicate events
Implementieren Sie Idempotenz mithilfe des
webhook-id-Headers, um dasselbe Ereignis gefahrlos mehrfach zu verarbeiten ohne Nebenwirkungen.Secure your webhook secret
Secure your webhook secret
Speichern Sie Ihren Webhook-Geheimschlüssel sicher in Umgebungsvariablen oder einem Secrets-Manager. Committen Sie Geheimnisse niemals in ein Versionsverwaltungssystem.
Webhook-Nutzlaststruktur
Das Verständnis der Webhook-Nutzlaststruktur hilft Ihnen, Ereignisse korrekt zu analysieren und zu verarbeiten.Anfrageformat
Header
Einzigartige Kennung für dieses Webhook-Ereignis. Verwenden Sie diese für Idempotenzprüfungen.
HMAC-SHA256-Signatur zur Überprüfung der Webhook-Authentizität.
Unix-Zeitstempel (in Sekunden), wann der Webhook gesendet wurde.
Anfragekörper
Ihre Dodo Payments-Geschäftskennung.
Ereignistyp, der dieses Webhook ausgelöst hat (z. B.
payment.succeeded, subscription.active).ISO-8601-formatierter Zeitstempel, wann das Ereignis stattgefunden hat.
Eventspezifische Nutzlast mit detaillierten Informationen zum Ereignis.
Beispiel-Nutzlast
Event Types
Durchsuchen Sie alle verfügbaren Webhook-Ereignistypen
Event Payloads
Sehen Sie sich die detaillierten Payload-Schemata für jedes Ereignis an
Webhooks testen
Sie können Ihre Webhook-Integration direkt über das Dodo Payments-Dashboard testen, um sicherzustellen, dass Ihr Endpunkt korrekt funktioniert, bevor Sie live gehen.
Zugriff auf die Testoberfläche
Navigate to Webhooks
Gehen Sie zum Dodo Payments Dashboard und navigieren Sie zu
Settings > Webhooks.Testen Sie Ihren Webhook
Die Testoberfläche bietet eine umfassende Möglichkeit, Ihren Webhook-Endpunkt zu testen:Select Event Type
Verwenden Sie das Dropdown-Menü, um den spezifischen Ereignistyp auszuwählen, den Sie testen möchten (z. B.
payment.succeeded, payment.failed usw.).Das Dropdown enthält alle verfügbaren Webhook-Ereignistypen, die Ihr Endpunkt empfangen kann.
Review Schema and Example
Die Oberfläche zeigt sowohl das Schema (Datenstruktur) als auch das Beispiel (Beispiel-Payload) für den ausgewählten Ereignistyp.
Überprüfen Sie Ihren Test
Check Your Endpoint
Überwachen Sie die Protokolle Ihres Webhook-Endpunkts, um zu bestätigen, dass das Testereignis empfangen wurde.
Verify Signature
Stellen Sie sicher, dass Ihre Signaturverifizierung mit der Test-Payload korrekt funktioniert.
Implementierungsbeispiel
Hier ist eine vollständige Implementierung in Express.js, die die Webhook-Überprüfung und -Verarbeitung zeigt:Testen von Webhooks mit der CLI
Die Dodo Payments CLI bietet zwei Befehle zum Testen von Webhooks während der lokalen Entwicklung, ohne das Terminal verlassen zu müssen.Live-Webhooks lokal abhören
Leiten Sie echte Webhook-Ereignisse aus Ihrem Testmodus-Konto in Echtzeit an Ihren lokalen Entwicklungsserver weiter:http://localhost:3000/webhook), wobei alle Header einschließlich der Signatur-Header für Verifizierungstests erhalten bleiben.
Der Listener funktioniert nur mit API-Schlüsseln für den Testmodus. Führen Sie
dodo login aus und wählen Sie den Testmodus aus, bevor Sie diesen Befehl verwenden.Auslösen von simulierten Webhook-Ereignissen
Senden Sie simulierte Webhook-Payloads an beliebige Endpunkte, ohne echte Transaktionen zu erstellen:CLI Webhook Testing Docs
Lesen Sie die vollständige CLI-Webhooks-Testdokumentation
Erweiterte Einstellungen
Die Registerkarte „Erweiterte Einstellungen“ bietet zusätzliche Konfigurationsoptionen zur Feinabstimmung des Verhaltens Ihres Webhook-Endpunkts.Ratenbegrenzung (Throttling)
Steuern Sie die Rate, mit der Webhook-Ereignisse an Ihren Endpunkt zugestellt werden, um eine Überlastung Ihres Systems zu verhindern.Configure Rate Limit
Klicken Sie auf die Edit-Schaltfläche, um die Ratenlimit-Einstellungen zu ändern.
Standardmäßig gilt für Webhooks „Kein Ratenlimit“, was bedeutet, dass Ereignisse sofort nach ihrem Auftreten zugestellt werden.
Benutzerdefinierte Header
Fügen Sie allen an Ihren Endpunkt gesendeten Webhook-Anfragen benutzerdefinierte HTTP-Header hinzu. Das ist nützlich für Authentifizierung, Routing oder das Hinzufügen von Metadaten zu Ihren Webhook-Anfragen.Add Custom Header
Geben Sie im Abschnitt „Custom Headers“ einen Schlüssel und einen Wert für Ihren benutzerdefinierten Header ein.
Add Multiple Headers
Klicken Sie auf die +-Schaltfläche, um bei Bedarf weitere benutzerdefinierte Header hinzuzufügen.
Transformationen
Transformationen ermöglichen es Ihnen, die Payload eines Webhooks zu ändern und ihn an eine andere URL weiterzuleiten. Dieses leistungsstarke Feature erlaubt Ihnen, Folgendes zu tun:- Die Payload-Struktur vor der Verarbeitung ändern
- Webhooks je nach Inhalt an verschiedene Endpunkte weiterleiten
- Felder zur Payload hinzufügen oder entfernen
- Datenformate transformieren
Configure Transformation
Klicken Sie auf Edit transformation, um Ihre Transformationsregeln festzulegen.
Sie können JavaScript verwenden, um die Webhook-Payload zu transformieren und eine andere Ziel-URL anzugeben.
Überwachung von Webhook-Protokollen
Die Registerkarte „Logs“ bietet umfassende Einblicke in den Zustellungsstatus Ihrer Webhooks, sodass Sie Ereignisse effektiv überwachen, debuggen und verwalten können.
Aktivitätsüberwachung
Die Registerkarte „Activity“ bietet Echtzeitinformationen zur Leistungsfähigkeit der Webhook-Zustellung mit visuellen Analysen.
E-Mail-Benachrichtigungen
Bleiben Sie durch automatische E-Mail-Benachrichtigungen über den Zustand Ihrer Webhooks informiert. Wenn die Zustellung fehlschlägt oder Ihr Endpunkt nicht mehr reagiert, erhalten Sie E-Mail-Warnungen, damit Sie Probleme schnell beheben und Ihre Integrationen reibungslos betreiben können.
E-Mail-Benachrichtigungen aktivieren
Navigate to Alerting Settings
Rufen Sie Ihr Dodo Payments Dashboard auf und navigieren Sie zu Dashboard → Webhooks → Alerting.
Enable Email Notifications
Schalten Sie Email notifications ein, um Warnungen zu Webhook-Zustellproblemen zu erhalten.
Bereitstellung auf Cloud-Plattformen
Bereit für den produktiven Einsatz Ihres Webhook-Handlers? Wir bieten plattformspezifische Anleitungen, um Webhooks mit Best Practices für jeden Anbieter auf beliebten Cloud-Plattformen bereitzustellen.Vercel
Deploy webhooks to Vercel with serverless functions
Cloudflare Workers
Run webhooks on Cloudflare’s edge network
Supabase Edge Functions
Integrate webhooks with Supabase
Netlify Functions
Deploy webhooks as Netlify serverless functions
Jeder Plattform-Guide enthält Anleitungen zur Einrichtung der Umgebung, Signaturverifizierung und den bereichsspezifischen Bereitstellungsschritten.
