Zum Hauptinhalt springen
Titelbild für Webhooks
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, 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

1

Access Webhook Settings

Navigieren Sie zum DodoPayments-Dashboard und gehen Sie zu Settings > Webhooks.
2

Create Webhook Endpoint

Klicken Sie auf Add Webhook, um einen neuen Webhook-Endpunkt zu erstellen.
Webhook hinzufügen
3

Add Endpoint URL

Geben Sie die URL ein, unter der Sie Webhook-Ereignisse empfangen möchten.
4

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.
Nur ausgewählte Ereignisse lösen Webhooks zu Ihrem Endpunkt aus, damit Sie unnötigen Traffic und Verarbeitung vermeiden.
5

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.
Halten Sie Ihren Webhook-Geheimschlüssel sicher und geben Sie ihn niemals in Client-Code oder öffentlichen Repositories preis.
6

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.
Durch das Rotieren wird der Geheimschlüssel ungültig und durch einen neuen ersetzt. Der alte Schlüssel bleibt nur für die nächsten 24 Stunden gültig. Danach schlägt die Verifizierung mit dem alten Schlüssel fehl.
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

1

Navigate to Webhook Details

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

Select Your Endpoint

Klicken Sie auf den Webhook-Endpunkt, den Sie konfigurieren möchten.
3

Open Event Settings

In der Detailseite zum Webhook sehen Sie den Abschnitt „Subscribed events“. Klicken Sie auf die Edit-Schaltfläche, um Ihre Ereignisabonnements zu ändern.

Ereignisabonnements verwalten

1

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

Search and Filter

Verwenden Sie die Suchleiste, um bestimmte Ereignisse schnell zu finden, indem Sie Ereignisnamen oder Schlüsselwörter eingeben.
3

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
4

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

Save Configuration

Klicken Sie auf Save, um Ihre Änderungen zu übernehmen, oder auf Cancel, um sie zu verwerfen.
Wenn Sie alle Ereignisse abwählen, erhält Ihr Webhook-Endpunkt keine Benachrichtigungen mehr. 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 eigentliche 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 zugestellt wird, beträgt die gesamte Lieferzeit ab dem ersten Versuch etwa 35 Minuten und 5 Sekunden.
Verwenden Sie das Dodo Payments Dashboard, um einzelne Nachrichten manuell erneut zu versuchen oder alle fehlgeschlagenen Nachrichten jederzeit gesammelt wiederherzustellen.

Idempotenz

Jedes Webhook-Ereignis enthält einen einzigartigen webhook-id-Header. Verwenden Sie diesen Bezeichner, um Idempotenz zu implementieren und doppelte Verarbeitung zu vermeiden.
// 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...
});
Führen Sie stets Idempotenzprüfungen durch. Aufgrund von Wiederholungen können Sie dasselbe Ereignis mehrfach 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 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 einen webhook-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üssels
  • unsafe_unwrap(): Analysiert Nutzlasten ohne Verifizierung
Geben Sie Ihren Webhook-Geheimschlüssel ü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 den exakten, rohen, in einen String umgewandelten payload mit Punkten (.) trennen und aneinanderreihen.
  2. Berechnen Sie die HMAC-SHA256 dieses Strings mithilfe Ihres Webhook-Geheimschlüssels vom Dashboard.
  3. 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 code zurückgeben, um den Empfang des Ereignisses zu bestätigen.
  • Jede andere Antwort wird als Fehler behandelt und der Webhook wird erneut gesendet.

Beste Praktiken

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.
Geben Sie sofort beim Empfang des Webhooks einen 200-Statuscode zurück. Verarbeiten Sie das Ereignis asynchron, um Timeouts 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 gefahrlos mehrfach zu verarbeiten ohne Nebenwirkungen.
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

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

Anfragekörper

business_id
string
erforderlich
Ihre Dodo Payments-Geschäftskennung.
type
string
erforderlich
Ereignistyp, der dieses Webhook ausgelöst hat (z. B. payment.succeeded, subscription.active).
timestamp
string
erforderlich
ISO-8601-formatierter Zeitstempel, wann das Ereignis stattgefunden hat.
data
object
erforderlich
Eventspezifische Nutzlast mit detaillierten Informationen zum 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.
Details des Endpunkts

Zugriff auf die Testoberfläche

1

Navigate to Webhooks

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

Select Your Endpoint

Klicken Sie auf Ihren Webhook-Endpunkt, um dessen Detailseite aufzurufen.
3

Open Testing Tab

Klicken Sie auf die Testing-Registerkarte, 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

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

Review Schema and Example

Die Oberfläche zeigt sowohl das Schema (Datenstruktur) als auch das Beispiel (Beispiel-Payload) für den ausgewählten Ereignistyp.
3

Send Test Event

Klicken Sie auf die Send Example-Schaltfläche, um einen Testwebhook an Ihren Endpunkt zu senden.
Wichtig: Fehlgeschlagene Nachrichten, die über die Testoberfläche gesendet werden, werden nicht erneut versendet. Dies dient ausschließlich Testzwecken.

Überprüfen Sie Ihren Test

1

Check Your Endpoint

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

Verify Signature

Stellen Sie sicher, dass Ihre Signaturverifizierung mit der Test-Payload korrekt funktioniert.
3

Test Response

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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
Testen Sie Ihren Webhook-Handler gründlich über die Dashboard-Testoberfläche, bevor Sie Produktionsereignisse verarbeiten. So können Sie Probleme frühzeitig erkennen und beheben.

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:
dodo wh listen
Die CLI öffnet eine WebSocket-Verbindung zu Dodo Payments und leitet jedes Webhook-Ereignis an Ihren lokalen Endpunkt weiter (z. B. 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:
dodo wh trigger
Dieses interaktive Tool ermöglicht es Ihnen, aus allen 22 unterstützten Ereignistypen auszuwählen und realistische simulierte Payloads an Ihren Endpunkt zu senden. Es wiederholt sich, sodass Sie mehrere Ereignisse in einer Sitzung testen können.
Simulierte Webhook-Payloads von dodo wh trigger sind nicht signiert. Verwenden Sie unsafe_unwrap() anstelle von unwrap() in Ihrem Webhook-Handler nur während des Testens.

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

Access Rate Limit Settings

Suchen Sie im Advanced-Tab den Abschnitt „Rate Limit (throttling)“.
2

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

Set Limits

Konfigurieren Sie das gewünschte Ratenlimit, um die Häufigkeit der Webhook-Zustellungen zu steuern und Systemüberlastung zu vermeiden.
Verwenden Sie Ratenbegrenzung, wenn Ihr Webhook-Handler Zeit zur Verarbeitung benötigt oder wenn Sie mehrere Ereignisse gemeinsam verarbeiten möchten.

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

Add Custom Header

Geben Sie im Abschnitt „Custom Headers“ einen Schlüssel und einen Wert für Ihren benutzerdefinierten Header ein.
2

Add Multiple Headers

Klicken Sie auf die +-Schaltfläche, um bei Bedarf weitere benutzerdefinierte Header hinzuzufügen.
3

Save Configuration

Ihre benutzerdefinierten Header werden in allen Webhook-Anfragen an diesen Endpunkt enthalten sein.

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
1

Enable Transformations

Schalten Sie den Enabled-Schalter ein, um die Transformation zu aktivieren.
2

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

Test Transformation

Verwenden Sie die Testoberfläche, um sicherzustellen, dass Ihre Transformation korrekt funktioniert, bevor sie live geht.
Transformationen können die Webhook-Zustellleistung erheblich beeinflussen. Testen Sie gründlich und halten Sie die Transformationslogik einfach und effizient.
Transformationen sind besonders nützlich für:
  • Konvertierungen zwischen verschiedenen Datenformaten
  • Filtern von Ereignissen nach bestimmten Kriterien
  • Hinzufügen berechneter Felder zur Payload
  • Weiterleitung von Ereignissen an verschiedene Microservices

Ü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.
Protokolle

Aktivitätsüberwachung

Die Registerkarte „Activity“ bietet Echtzeitinformationen zur Leistungsfähigkeit der Webhook-Zustellung mit visuellen Analysen.
Aktivität

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.
Einstellungen für Webhook-Benachrichtigungen mit E-Mail-Konfigurationsanzeige

E-Mail-Benachrichtigungen aktivieren

1

Navigate to Alerting Settings

Rufen Sie Ihr Dodo Payments Dashboard auf und navigieren Sie zu Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Schalten Sie Email notifications ein, um Warnungen zu Webhook-Zustellproblemen zu erhalten.
3

Configure Email Address

Geben Sie die E-Mail-Adresse ein, an die Sie Webhook-Warnungen erhalten möchten. Wir senden Benachrichtigungen an diese Adresse, wenn bestimmte Ereignisse in Ihrer Webhook-Konfiguration auftreten, z. B. Zustellprobleme, die Ihre Integrationen beeinträchtigen könnten.
Aktivieren Sie E-Mail-Benachrichtigungen, um Probleme bei der Webhook-Zustellung frühzeitig zu erkennen und zuverlässige Integrationen zu gewährleisten. Sie werden benachrichtigt, wenn Zustellungen fehlschlagen oder Ihr Endpunkt nicht mehr reagiert.

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.
Jeder Plattform-Guide enthält Anleitungen zur Einrichtung der Umgebung, Signaturverifizierung und den bereichsspezifischen Bereitstellungsschritten.