Erhalten Sie Echtzeitbenachrichtigungen, wenn Ereignisse in Dodo Payments auftreten. Automatisieren Sie Workflows und halten Sie Ihre Systeme mit sofortiger Ereignislieferung synchron.
Webhooks bieten Echtzeitbenachrichtigungen, wenn bestimmte Ereignisse in Ihrem Dodo Payments-Konto auftreten. Verwenden Sie Webhooks, um Workflows zu automatisieren, Ihre Datenbank zu aktualisieren, Benachrichtigungen zu senden und Ihre Systeme synchron zu halten.
Unsere Webhook-Implementierung folgt der Standard Webhooks Spezifikation, um die Kompatibilität mit den besten Praktiken der Branche und bestehenden Webhook-Bibliotheken sicherzustellen.
Navigieren Sie zum DodoPayments-Dashboard und gehen Sie zu Settings > Webhooks.
2
Webhook-Endpunkt erstellen
Klicken Sie auf Add Webhook, um einen neuen Webhook-Endpunkt zu erstellen.
3
Endpunkt-URL hinzufügen
Geben Sie die URL ein, an die Sie Webhook-Ereignisse empfangen möchten.
4
Ereignisse zum Empfangen auswählen
Wählen Sie die spezifischen Ereignisse aus, auf die Ihr Webhook-Endpunkt hören soll, indem Sie sie aus der Ereignisliste auswählen.
Nur ausgewählte Ereignisse lösen Webhooks an Ihren Endpunkt aus, was Ihnen hilft, unnötigen Datenverkehr und Verarbeitung zu vermeiden.
5
Geheimschlüssel abrufen
Erhalten Sie Ihren Webhook Secret Key von der Einstellungsseite. Sie verwenden dies, um die Authentizität der empfangenen Webhooks zu überprüfen.
Halten Sie Ihren Webhook-Geheimschlüssel sicher und geben Sie ihn niemals in clientseitigem Code oder öffentlichen Repositories preis.
6
Geheimnis rotieren (optional)
Wenn nötig, können Sie Ihr Webhook-Geheimnis zur Verbesserung der Sicherheit rotieren. Klicken Sie auf die Schaltfläche Geheimnis rotieren in Ihren Webhook-Einstellungen.
Das Rotieren des Geheimnisses wird es ablaufen lassen und durch ein neues ersetzen. Das alte Geheimnis ist nur für die nächsten 24 Stunden gültig. Danach wird der Versuch, mit dem alten Geheimnis zu verifizieren, fehlschlagen.
Verwenden Sie die Geheimnisrotation regelmäßig oder sofort, wenn Sie vermuten, dass Ihr aktuelles Geheimnis kompromittiert wurde.
Gehen Sie zu Ihrem Dodo Payments-Dashboard und navigieren Sie zu Settings > Webhooks.
2
Wählen Sie Ihren Endpunkt aus
Klicken Sie auf den Webhook-Endpunkt, den Sie konfigurieren möchten.
3
Ereigniseinstellungen öffnen
Auf der Seite mit den Webhook-Details sehen Sie einen Abschnitt “Abonnierte Ereignisse”. Klicken Sie auf die Schaltfläche Bearbeiten, um Ihre Ereignisabonnements zu ändern.
Die Benutzeroberfläche zeigt alle verfügbaren Webhook-Ereignisse, die in einer hierarchischen Struktur organisiert sind. Ereignisse sind nach Kategorien gruppiert (z. B. dispute, payment, subscription).
2
Suchen und Filtern
Verwenden Sie die Suchleiste, um spezifische Ereignisse schnell zu finden, indem Sie Ereignisnamen oder Schlüsselwörter eingeben.
3
Ereignisse auswählen
Aktivieren Sie die Kästchen neben den Ereignissen, die Sie empfangen möchten. Sie können:
Einzelne Unterereignisse auswählen (z. B. dispute.accepted, dispute.challenged)
Übergeordnete Ereignisse auswählen, um alle zugehörigen Unterereignisse zu empfangen
Bestimmte Ereignisse basierend auf Ihren Bedürfnissen kombinieren und anpassen
4
Ereignisdetails überprüfen
Fahren Sie mit der Maus über das Informationssymbol (ⓘ) neben jedem Ereignis, um eine Beschreibung zu sehen, wann dieses Ereignis ausgelöst wird.
5
Konfiguration speichern
Klicken Sie auf Speichern, um Ihre Änderungen anzuwenden, oder auf Abbrechen, um Änderungen zu verwerfen.
Wenn Sie alle Ereignisse abwählen, erhält Ihr Webhook-Endpunkt keine Benachrichtigungen. Stellen Sie sicher, dass Sie mindestens die Ereignisse auswählen, die Ihre Anwendung benötigt, um ordnungsgemäß zu funktionieren.
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.
Verarbeiten Sie Webhooks asynchron, indem Sie den Empfang sofort mit einem 200 Statuscode bestätigen und die tatsächliche Verarbeitung im Hintergrund durchführen.
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 ist, beträgt die gesamte Lieferzeit ungefähr 35 Minuten und 5 Sekunden ab dem ersten Versuch.
Verwenden Sie das Dodo Payments-Dashboard, um einzelne Nachrichten manuell erneut zu versuchen oder alle fehlgeschlagenen Nachrichten jederzeit in großen Mengen wiederherzustellen.
Jedes Webhook-Ereignis enthält einen eindeutigen webhook-id Header. Verwenden Sie diesen Identifikator, um Idempotenz zu implementieren und doppelte Verarbeitung zu verhindern.
Kopieren
// 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 können Sie dasselbe Ereignis mehrere Male erhalten.
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 neueste Nutzlast zum Zeitpunkt der Lieferung, unabhängig davon, wann das Webhook-Ereignis ursprünglich ausgegeben wurde.
Jede Webhook-Anfrage enthält einen webhook-signature Header, eine HMAC SHA256 Signatur der Webhook-Nutzlast und des Zeitstempels, signiert mit Ihrem geheimen Schlüssel.
Alle offiziellen SDKs enthalten integrierte Hilfsfunktionen zur sicheren Validierung und Analyse eingehender Webhooks. Es stehen zwei Methoden zur Verfügung:
unwrap(): Überprüft Signaturen mit Ihrem Webhook-Geheimschlüssel
unsafe_unwrap(): Analysiert Nutzlasten ohne Überprüfung
Geben Sie Ihr Webhook-Geheimnis über DODO_PAYMENTS_WEBHOOK_KEY bei der Initialisierung des Dodo Payments-Clients an.
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-timestamp und die genaue rohe, stringifizierte payload, getrennt durch Punkte (.), verketten.
Berechnen Sie die HMAC SHA256 dieser Zeichenfolge mit Ihrem Webhook-Geheimschlüssel aus dem Dashboard.
Vergleichen Sie die berechnete Signatur mit dem webhook-signature Header. Wenn sie übereinstimmen, ist der Webhook authentisch.
Verwenden Sie immer HTTPS-URLs für Webhook-Endpunkte. HTTP-Endpunkte sind anfällig für Man-in-the-Middle-Angriffe und setzen Ihre Webhook-Daten aus.
Sofortige Antwort
Geben Sie sofort einen 200 Statuscode zurück, sobald Sie den Webhook erhalten. Verarbeiten Sie das Ereignis asynchron, um Zeitüberschreitungen zu vermeiden.
Implementieren Sie Idempotenz mithilfe des webhook-id Headers, um dasselbe Ereignis sicher mehrere Male ohne Nebenwirkungen zu verarbeiten.
Sichern Sie Ihr Webhook-Geheimnis
Speichern Sie Ihr Webhook-Geheimnis sicher mit Umgebungsvariablen oder einem Geheimnismanager. Geben Sie Geheimnisse niemals in die Versionskontrolle ein.
Sie können Ihre Webhook-Integration direkt über das Dodo Payments-Dashboard testen, um sicherzustellen, dass Ihr Endpunkt korrekt funktioniert, bevor Sie live gehen.
Hier ist eine vollständige Implementierung in Express.js, die die Webhook-Überprüfung und -Verarbeitung zeigt:
Kopieren
import { Webhook } from "standardwebhooks";import express from "express";const app = express();app.use(express.json());const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);app.post('/webhook/dodo-payments', async (req, res) => { try { // Extract webhook headers const webhookHeaders = { "webhook-id": req.headers["webhook-id"] as string, "webhook-signature": req.headers["webhook-signature"] as string, "webhook-timestamp": req.headers["webhook-timestamp"] as string, }; // Verify the webhook signature const payload = JSON.stringify(req.body); await webhook.verify(payload, webhookHeaders); // Acknowledge receipt immediately res.status(200).json({ received: true }); // Process webhook asynchronously processWebhookAsync(req.body).catch(console.error); } catch (error) { console.error('Webhook verification failed:', error); res.status(400).json({ error: 'Invalid signature' }); }});async function processWebhookAsync(data: any) { // Handle the webhook event based on type switch (data.type) { case 'payment.succeeded': await handlePaymentSucceeded(data); break; case 'subscription.created': await handleSubscriptionCreated(data); break; // Add more event handlers... }}
Testen Sie Ihren Webhook-Handler gründlich mit der Testoberfläche des Dashboards, bevor Sie Produktionsereignisse verarbeiten. Dies hilft, Probleme frühzeitig zu identifizieren und zu beheben.
Steuern Sie die Rate, mit der Webhook-Ereignisse an Ihren Endpunkt geliefert werden, um eine Überlastung Ihres Systems zu verhindern.
1
Zugriff auf die Ratenlimit-Einstellungen
Im Tab Erweitert finden Sie den Abschnitt “Ratenlimit (Throttling)”.
2
Ratenlimit konfigurieren
Klicken Sie auf die Schaltfläche Bearbeiten, um die Ratenlimiteinstellungen zu ändern.
Standardmäßig haben Webhooks “Kein Ratenlimit”, was bedeutet, dass Ereignisse sofort nach ihrem Auftreten geliefert werden.
3
Grenzen festlegen
Konfigurieren Sie Ihr gewünschtes Ratenlimit, um die Häufigkeit der Webhook-Lieferung zu steuern und eine Überlastung des Systems zu verhindern.
Verwenden Sie die Ratenbegrenzung, wenn Ihr Webhook-Handler Zeit benötigt, um Ereignisse zu verarbeiten, oder wenn Sie mehrere Ereignisse zusammenfassen möchten.
Fügen Sie allen Webhook-Anfragen, die an Ihren Endpunkt gesendet werden, benutzerdefinierte HTTP-Header hinzu. Dies ist nützlich für Authentifizierung, Routing oder das Hinzufügen von Metadaten zu Ihren Webhook-Anfragen.
1
Benutzerdefinierten Header hinzufügen
Geben Sie im Abschnitt “Benutzerdefinierte Header” einen Schlüssel und Wert für Ihren benutzerdefinierten Header ein.
2
Mehrere Header hinzufügen
Klicken Sie auf die Schaltfläche +, um bei Bedarf zusätzliche benutzerdefinierte Header hinzuzufügen.
3
Konfiguration speichern
Ihre benutzerdefinierten Header werden in allen Webhook-Anfragen an diesen Endpunkt enthalten sein.
Transformationen ermöglichen es Ihnen, die Nutzlast eines Webhooks zu ändern und an eine andere URL umzuleiten. Diese leistungsstarke Funktion ermöglicht es Ihnen,:
Die Nutzlaststruktur vor der Verarbeitung zu ändern
Webhooks basierend auf Inhalten an verschiedene Endpunkte weiterzuleiten
Felder aus der Nutzlast hinzuzufügen oder zu entfernen
Datenformate zu transformieren
1
Transformationen aktivieren
Schalten Sie den Schalter Aktiviert um, um die Transformationsfunktion zu aktivieren.
2
Transformation konfigurieren
Klicken Sie auf Transformation bearbeiten, um Ihre Transformationsregeln zu definieren.
Sie können JavaScript verwenden, um die Webhook-Nutzlast zu transformieren und eine andere Ziel-URL anzugeben.
3
Transformation testen
Verwenden Sie die Testoberfläche, um zu überprüfen, ob Ihre Transformation korrekt funktioniert, bevor Sie live gehen.
Transformationen können die Leistung der Webhook-Lieferung erheblich beeinträchtigen. Testen Sie gründlich und halten Sie die Transformationslogik einfach und effizient.
Transformationen sind besonders nützlich für:
Konvertierung zwischen verschiedenen Datenformaten
Filtern von Ereignissen basierend auf spezifischen Kriterien
Hinzufügen von berechneten Feldern zur Nutzlast
Routen von Ereignissen zu verschiedenen Mikrodiensten
Der Tab “Protokolle” bietet umfassende Einblicke in den Lieferstatus Ihrer Webhooks, sodass Sie Webhook-Ereignisse effektiv überwachen, debuggen und verwalten können.
Bleiben Sie über die Gesundheit Ihrer Webhooks mit automatischen E-Mail-Benachrichtigungen informiert. Wenn die Webhook-Lieferungen fehlschlagen oder Ihr Endpunkt nicht mehr reagiert, erhalten Sie E-Mail-Benachrichtigungen, damit Sie Probleme schnell beheben und Ihre Integrationen reibungslos laufen lassen können.
Navigieren Sie zu den Benachrichtigungseinstellungen
Gehen Sie zu Ihrem Dodo Payments-Dashboard und navigieren Sie zu Dashboard → Webhooks → Benachrichtigungen.
2
E-Mail-Benachrichtigungen aktivieren
Schalten Sie E-Mail-Benachrichtigungen ein, um Benachrichtigungen über Probleme mit der Webhook-Lieferung zu erhalten.
3
E-Mail-Adresse konfigurieren
Geben Sie die E-Mail-Adresse ein, an die Sie Webhook-Benachrichtigungen erhalten möchten. Wir senden Benachrichtigungen an diese Adresse, wenn bestimmte Ereignisse in Ihrer Webhook-Konfiguration auftreten, wie z. B. Lieferprobleme, die Ihre Integrationen beeinträchtigen könnten.
Aktivieren Sie E-Mail-Benachrichtigungen, um Webhook-Lieferprobleme frühzeitig zu erkennen und zuverlässige Integrationen aufrechtzuerhalten. Sie werden benachrichtigt, wenn Lieferungen fehlschlagen oder Ihr Endpunkt nicht mehr reagiert.
Bereit, Ihren Webhook-Handler in der Produktion bereitzustellen? Wir bieten plattformspezifische Anleitungen, um Ihnen zu helfen, Webhooks bei beliebten Cloud-Anbietern mit Best Practices für jede Plattform bereitzustellen.