Zum Hauptinhalt springen
Webhook Cover Image
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.

Hauptmerkmale

Echtzeitlieferung

Erhalten Sie sofortige Benachrichtigungen, wenn Ereignisse auftreten

Standardmäßig sicher

HMAC SHA256 Signaturverifizierung enthalten

Automatische Wiederholungen

Eingebaute Wiederholungslogik mit exponentiellem Backoff

Ereignisfilterung

Abonnieren Sie nur die Ereignisse, die Sie benötigen

Erste Schritte

1

Webhook-Einstellungen aufrufen

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.
Add Webhook
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.

Abonnierte Ereignisse konfigurieren

Sie können konfigurieren, welche spezifischen Ereignisse sie für jeden Webhook-Endpunkt empfangen möchten.

Zugriff auf die Ereigniskonfiguration

1

Navigieren Sie zu den Webhook-Details

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.

Ereignisabonnements verwalten

1

Verfügbare Ereignisse anzeigen

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.

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.
Verarbeiten Sie Webhooks asynchron, indem Sie den Empfang sofort mit einem 200 Statuscode bestätigen und die tatsächliche Verarbeitung im Hintergrund durchführen.

Automatische Wiederholungen

Wenn die Lieferung eines Webhooks fehlschlägt, versucht Dodo Payments automatisch mit exponentiellem Backoff, um zu verhindern, dass Ihr System überlastet wird.
VersuchVerzögerungBeschreibung
1SofortDer erste Versuch erfolgt sofort
25 SekundenDer zweite Versuch nach kurzer Verzögerung
35 MinutenDer dritte Versuch mit erhöhtem Backoff
430 MinutenDer vierte Versuch mit fortgesetztem Backoff
52 StundenDer fünfte Versuch mit verlängerter Verzögerung
65 StundenDer sechste Versuch mit längerer Verzögerung
710 StundenDer siebte Versuch mit maximaler Verzögerung
810 StundenLetzter 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.

Idempotenz

Jedes Webhook-Ereignis enthält einen eindeutigen webhook-id Header. Verwenden Sie diesen Identifikator, um Idempotenz zu implementieren und doppelte Verarbeitung zu verhindern.
// Example: Storing webhook IDs to prevent duplicate processing
const 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.

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 neueste Nutzlast zum Zeitpunkt der Lieferung, unabhängig davon, wann das Webhook-Ereignis ursprünglich ausgegeben 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 einen webhook-signature Header, eine HMAC SHA256 Signatur der Webhook-Nutzlast und des Zeitstempels, signiert mit Ihrem geheimen Schlü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 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.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Manuelle Überprüfung (Alternative)

Wenn Sie kein SDK verwenden, können Sie Signaturen selbst überprüfen, indem Sie der Standard-Webhooks-Spezifikation folgen:
  1. Erstellen Sie die signierte Nachricht, indem Sie webhook-id, webhook-timestamp und die genaue rohe, stringifizierte payload, getrennt durch Punkte (.), verketten.
  2. Berechnen Sie die HMAC SHA256 dieser Zeichenfolge mit Ihrem Webhook-Geheimschlüssel aus dem Dashboard.
  3. Vergleichen Sie die berechnete Signatur mit dem webhook-signature Header. Wenn sie übereinstimmen, ist der Webhook authentisch.
Wir folgen der Standard-Webhooks-Spezifikation. Sie können deren Bibliotheken verwenden, um Signaturen zu überprüfen: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Für die Formate der Ereignisnutzlasten siehe die Webhook-Nutzlast.

Auf Webhooks reagieren

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

Beste Praktiken

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.
Geben Sie sofort einen 200 Statuscode zurück, sobald Sie den Webhook erhalten. Verarbeiten Sie das Ereignis asynchron, um Zeitüberschreitungen zu vermeiden.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implementieren Sie Idempotenz mithilfe des webhook-id Headers, um dasselbe Ereignis sicher mehrere Male ohne Nebenwirkungen zu verarbeiten.
Speichern Sie Ihr Webhook-Geheimnis sicher mit Umgebungsvariablen oder einem Geheimnismanager. Geben Sie Geheimnisse niemals in die Versionskontrolle ein.

Webhook-Nutzlaststruktur

Das Verständnis der Webhook-Nutzlaststruktur hilft Ihnen, Ereignisse korrekt zu analysieren und zu verarbeiten.

Anfrageformat

POST /your-webhook-url
Content-Type: application/json
webhook-id
string
required
Eindeutige Kennung für dieses Webhook-Ereignis. Verwenden Sie dies für Idempotenzprüfungen.
webhook-signature
string
required
HMAC SHA256 Signatur zur Überprüfung der Authentizität des Webhooks.
webhook-timestamp
string
required
Unix-Zeitstempel (in Sekunden), wann der Webhook gesendet wurde.

Anfragekörper

business_id
string
required
Ihre Dodo Payments-Geschäftskennung.
type
string
required
Ereignistyp, der diesen Webhook ausgelöst hat (z. B. payment.succeeded, subscription.created).
timestamp
string
required
ISO 8601 formatierter Zeitstempel, wann das Ereignis aufgetreten ist.
data
object
required
Ereignisspezifische Nutzlast mit detaillierten Informationen über das Ereignis.

Beispiel-Nutzlast

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

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.
Endpoint Details

Zugriff auf die Testoberfläche

1

Navigieren Sie zu Webhooks

Gehen Sie zu Ihrem Dodo Payments-Dashboard und navigieren Sie zu Settings > Webhooks.
2

Wählen Sie Ihren Endpunkt aus

Klicken Sie auf Ihren Webhook-Endpunkt, um auf die Detailseite zuzugreifen.
3

Test-Tab öffnen

Klicken Sie auf den Tab Testen, um auf die Webhook-Testoberfläche zuzugreifen.

Testen Sie Ihren Webhook

Die Testoberfläche bietet eine umfassende Möglichkeit, Ihren Webhook-Endpunkt zu testen:
1

Ereignistyp auswählen

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.
2

Schema und Beispiel überprüfen

Die Benutzeroberfläche zeigt sowohl das Schema (Datenstruktur) als auch das Beispiel (Beispielnutzlast) für den ausgewählten Ereignistyp an.
3

Testereignis senden

Klicken Sie auf die Schaltfläche Beispiel senden, um einen Test-Webhook an Ihren Endpunkt zu senden.
Wichtig: Fehlgeschlagene Nachrichten, die über die Testoberfläche gesendet werden, werden nicht erneut versucht. Dies dient nur zu Testzwecken.

Überprüfen Sie Ihren Test

1

Überprüfen Sie Ihren Endpunkt

Überwachen Sie die Protokolle Ihres Webhook-Endpunkts, um zu bestätigen, dass das Testereignis empfangen wurde.
2

Signatur überprüfen

Stellen Sie sicher, dass Ihre Signaturüberprüfung mit der Testnutzlast korrekt funktioniert.
3

Testantwort

Bestätigen Sie, dass Ihr Endpunkt einen 2xx Statuscode zurückgibt, um den Empfang zu bestätigen.

Implementierungsbeispiel

Hier ist eine vollständige Implementierung in Express.js, die die Webhook-Überprüfung und -Verarbeitung zeigt:
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.

Erweiterte Einstellungen

Der Tab “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 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.

Benutzerdefinierte Header

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

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

Überwachung der Webhook-Protokolle

Der Tab “Protokolle” bietet umfassende Einblicke in den Lieferstatus Ihrer Webhooks, sodass Sie Webhook-Ereignisse effektiv überwachen, debuggen und verwalten können.
Logs

Aktivitätsüberwachung

Der Tab “Aktivität” bietet Echtzeiteinblicke in die Leistung Ihrer Webhook-Lieferung mit visuellen Analysen.
Activity

E-Mail-Benachrichtigungen

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.
Webhook Alerting Settings showing email notifications configuration

E-Mail-Benachrichtigungen aktivieren

1

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.

Bereitstellung auf Cloud-Plattformen

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.
Jede Plattformanleitung enthält Umgebungssetup, Signaturüberprüfung und Bereitstellungsschritte, die spezifisch für diesen Anbieter sind.