Passer au contenu principal
Webhook Cover Image
Les webhooks fournissent des notifications en temps réel lorsque des événements spécifiques se produisent dans votre compte Dodo Payments. Utilisez les webhooks pour automatiser les flux de travail, mettre à jour votre base de données, envoyer des notifications et garder vos systèmes synchronisés.
Notre implémentation des webhooks suit la spécification Standard Webhooks, garantissant une compatibilité avec les meilleures pratiques du secteur et les bibliothèques de webhooks existantes.

Caractéristiques clés

Real-time Delivery

Recevez des notifications instantanées lorsque des événements se produisent

Secure by Default

Vérification des signatures HMAC SHA256 incluse

Automatic Retries

Logique de relance intégrée avec backoff exponentiel

Event Filtering

Abonnez-vous uniquement aux événements dont vous avez besoin

Commencer

1

Access Webhook Settings

Accédez au tableau de bord DodoPayments et rendez-vous sur Settings > Webhooks.
2

Create Webhook Endpoint

Cliquez sur Add Webhook pour créer un nouvel endpoint webhook.
Add Webhook
3

Add Endpoint URL

Saisissez l’URL où vous souhaitez recevoir les événements webhook.
4

Select Events to Receive

Choisissez les événements spécifiques que votre endpoint webhook doit écouter en les sélectionnant dans la liste des événements.
Seuls les événements sélectionnés déclencheront des webhooks vers votre endpoint, ce qui vous aide à éviter le trafic et le traitement inutile.
5

Get Secret Key

Obtenez votre Secret Key webhook depuis la page de paramètres. Vous utiliserez cette clé pour vérifier l’authenticité des webhooks reçus.
Gardez votre clé secrète webhook sécurisée et ne l’exposez jamais dans du code client ou des dépôts publics.
6

Rotate Secret (Optional)

Si nécessaire, vous pouvez faire pivoter votre clé secrète webhook pour renforcer la sécurité. Cliquez sur le bouton Rotate Secret dans les paramètres de votre webhook.
Faire pivoter le secret le désactivera et le remplacera par un nouveau. L’ancien secret restera valide uniquement pendant les 24 heures suivantes. Passé ce délai, toute vérification avec l’ancien secret échouera.
Utilisez la rotation de secret périodiquement ou immédiatement si vous suspectez que votre secret actuel a été compromis.

Configuration des événements abonnés

Vous pouvez configurer quels événements spécifiques vous souhaitez recevoir pour chaque point de terminaison de webhook.

Accéder à la configuration des événements

1

Navigate to Webhook Details

Allez sur votre tableau de bord Dodo Payments et naviguez vers Settings > Webhooks.
2

Select Your Endpoint

Cliquez sur l’endpoint webhook que vous souhaitez configurer.
3

Open Event Settings

Sur la page de détails du webhook, vous verrez une section « Subscribed events ». Cliquez sur le bouton Edit pour modifier vos abonnements aux événements.

Gestion des abonnements d’événements

1

View Available Events

L’interface affiche tous les événements webhook disponibles organisés dans une structure hiérarchique. Les événements sont regroupés par catégorie (par exemple, dispute, payment, subscription).
2

Search and Filter

Utilisez la barre de recherche pour trouver rapidement des événements spécifiques en saisissant des noms ou des mots-clés.
3

Select Events

Cochez les cases à côté des événements que vous souhaitez recevoir. Vous pouvez :
  • Sélectionner des sous-événements individuels (par exemple, dispute.accepted, dispute.challenged)
  • Sélectionner des événements parents pour recevoir tous les sous-événements associés
  • Mixer et assortir des événements spécifiques selon vos besoins
4

Review Event Details

Survolez l’icône d’information (ⓘ) à côté de chaque événement pour voir une description du moment où cet événement est déclenché.
5

Save Configuration

Cliquez sur Save pour appliquer vos modifications ou sur Cancel pour les annuler.
Si vous désélectionnez tous les événements, votre endpoint webhook ne recevra aucune notification. Veillez à sélectionner au moins les événements dont votre application a besoin pour fonctionner correctement.

Livraison des webhooks

Délais d’attente

Les webhooks ont une fenêtre de délai d’attente de 15 secondes pour les opérations de connexion et de lecture. Assurez-vous que votre point de terminaison répond rapidement pour éviter les délais d’attente.
Traitez les webhooks de manière asynchrone en accusant réception immédiatement avec un code de statut 200, puis en effectuant le traitement effectif en arrière-plan.

Réessais automatiques

Si une livraison de webhook échoue, Dodo Payments réessaie automatiquement avec un backoff exponentiel pour éviter de surcharger votre système.
TentativeDélaiDescription
1ImmédiatementLe premier réessai se produit immédiatement
25 secondesDeuxième tentative après un court délai
35 minutesTroisième tentative avec un backoff accru
430 minutesQuatrième tentative continuant le backoff
52 heuresCinquième tentative avec un délai prolongé
65 heuresSixième tentative avec un délai plus long
710 heuresSeptième tentative avec un délai maximum
810 heuresDernière tentative - webhook marqué comme échoué si non réussi
Maximum de 8 tentatives de relance par événement webhook. Par exemple, si un webhook échoue trois fois avant de réussir, le délai total de livraison est d’environ 35 minutes et 5 secondes à partir de la première tentative.
Utilisez le tableau de bord Dodo Payments pour relancer manuellement des messages individuels ou récupérer en masse tous les messages échoués à tout moment.

Idempotence

Chaque événement webhook inclut un en-tête UNIQUE webhook-id. Utilisez cet identifiant pour mettre en œuvre l’idempotence et éviter un traitement en double.
// 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...
});
Mettez toujours en œuvre des contrôles d’idempotence. En raison des relances, vous pouvez recevoir plusieurs fois le même événement.

Ordre des événements

Les événements de webhook peuvent arriver dans le désordre en raison des réessais ou des conditions réseau. Concevez votre système pour gérer les événements dans n’importe quelle séquence.
Vous recevrez la charge utile la plus récente au moment de la livraison, indépendamment du moment où l’événement webhook a été émis à l’origine.

Sécurisation des webhooks

Pour garantir la sécurité de vos webhooks, validez toujours les payloads et utilisez HTTPS.

Vérification des signatures

Chaque requête webhook inclut un en-tête webhook-signature, une signature HMAC SHA256 du payload webhook et de l’horodatage, signée avec votre clé secrète.

Vérification SDK (recommandée)

Tous les SDK officiels incluent des helpers intégrés pour valider et analyser en toute sécurité les webhooks entrants. Deux méthodes sont disponibles :
  • unwrap() : vérifie les signatures en utilisant votre clé secrète webhook
  • unsafe_unwrap() : analyse les payloads sans vérification
Fournissez votre secret webhook via DODO_PAYMENTS_WEBHOOK_KEY lors de l’initialisation du client Dodo Payments.
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' });
  }
});

Vérification manuelle (alternative)

Si vous n’utilisez pas de SDK, vous pouvez vérifier les signatures vous-même en suivant la spécification des Webhooks Standards :
  1. Construisez le message signé en concaténant webhook-id, webhook-timestamp et la chaîne brute EXACTE stringifiée payload, séparées par des points (.).
  2. Calculez le HMAC SHA256 de cette chaîne en utilisant votre clé secrète webhook depuis le tableau de bord.
  3. Comparez la signature calculée avec l’en-tête webhook-signature. Si elles correspondent, le webhook est authentique.
Nous suivons la spécification Standard Webhooks. Vous pouvez utiliser leurs bibliothèques pour vérifier les signatures : https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Pour les formats de payloads d’événements, consultez le Webhook Payload.

Répondre aux webhooks

  • Votre gestionnaire de webhooks doit renvoyer un code 2xx status code pour accuser réception de l’événement.
  • Toute autre réponse sera considérée comme un échec, et le webhook sera relancé.

Meilleures pratiques

Utilisez toujours des URL HTTPS pour les endpoints webhook. Les endpoints HTTP sont vulnérables aux attaques de type man-in-the-middle et exposent vos données webhook.
Retournez immédiatement un code de statut 200 dès réception du webhook. Traitez l’événement de manière asynchrone pour éviter les dépassements de délai.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Mettez en œuvre l’idempotence à l’aide de l’en-tête webhook-id pour traiter en toute sécurité plusieurs fois le même événement sans effets secondaires.
Stockez votre secret webhook de manière sécurisée à l’aide de variables d’environnement ou d’un gestionnaire de secrets. Ne commettez jamais de secrets dans un contrôle de version.

Structure du payload de webhook

Comprendre la structure du payload de webhook vous aide à analyser et à traiter correctement les événements.

Format de requête

POST /your-webhook-url
Content-Type: application/json

En-têtes

webhook-id
string
requis
Identifiant unique pour cet événement webhook. Utilisez-le pour les vérifications d’idempotence.
webhook-signature
string
requis
Signature HMAC SHA256 pour vérifier l’authenticité du webhook.
webhook-timestamp
string
requis
Horodatage Unix (en secondes) indiquant quand le webhook a été envoyé.

Corps de la requête

business_id
string
requis
Votre identifiant d’entreprise Dodo Payments.
type
string
requis
Type d’événement ayant déclenché ce webhook (par exemple payment.succeeded, subscription.active).
timestamp
string
requis
Horodatage au format ISO 8601 indiquant quand l’événement s’est produit.
data
object
requis
Charge utile spécifique à l’événement contenant des informations détaillées sur celui-ci.

Exemple de payload

{
  "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)
  }
}

Tester les webhooks

Vous pouvez tester votre intégration de webhook directement depuis le tableau de bord Dodo Payments pour vous assurer que votre point de terminaison fonctionne correctement avant de passer en production.
Endpoint Details

Accéder à l’interface de test

1

Navigate to Webhooks

Accédez à votre tableau de bord Dodo Payments et rendez-vous sur Settings > Webhooks.
2

Select Your Endpoint

Cliquez sur votre endpoint webhook pour accéder à sa page de détails.
3

Open Testing Tab

Cliquez sur l’onglet Testing pour accéder à l’interface de test des webhooks.

Tester votre webhook

L’interface de test fournit un moyen complet de tester votre point de terminaison de webhook :
1

Select Event Type

Utilisez le menu déroulant pour sélectionner le type d’événement spécifique que vous souhaitez tester (par exemple, payment.succeeded, payment.failed, etc.).
Le menu déroulant contient tous les types d’événements webhook disponibles que votre endpoint peut recevoir.
2

Review Schema and Example

L’interface affiche à la fois le Schema (structure des données) et l’Example (payload d’exemple) pour le type d’événement sélectionné.
3

Send Test Event

Cliquez sur le bouton Send Example pour envoyer un webhook de test à votre endpoint.
Important : les messages échoués envoyés via l’interface de test ne seront pas relancés. Ceci est uniquement à des fins de test.

Vérifier votre test

1

Check Your Endpoint

Surveillez les journaux de votre endpoint webhook pour confirmer que l’événement de test a été reçu.
2

Verify Signature

Assurez-vous que votre vérification de signature fonctionne correctement avec le payload de test.
3

Test Response

Confirmez que votre endpoint renvoie un code de statut 2xx pour accuser réception.

Exemple d’implémentation

Voici une implémentation complète en Express.js montrant la vérification et le traitement des webhooks :
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...
  }
}
Testez soigneusement votre gestionnaire de webhooks à l’aide de l’interface de test du tableau de bord avant de traiter des événements en production. Cela permet d’identifier et de corriger les problèmes tôt.

Tester les webhooks avec le CLI

Le Dodo Payments CLI fournit deux commandes pour tester les webhooks lors du développement local, sans avoir besoin de quitter votre terminal.

Écouter les webhooks en direct localement

Transférez en temps réel les événements webhook réels de votre compte en mode test vers votre serveur de développement local :
dodo wh listen
Le CLI ouvre une connexion WebSocket vers Dodo Payments et transmet chaque événement webhook vers votre endpoint local (par exemple, http://localhost:3000/webhook), en conservant tous les en-têtes, y compris les en-têtes de signature pour les tests de vérification.
Le listener fonctionne uniquement avec des clés API en mode test. Exécutez dodo login et sélectionnez le mode Test avant d’utiliser cette commande.

Déclencher des événements webhook simulés

Envoyez des payloads webhook simulés à n’importe quel endpoint sans créer de transactions réelles :
dodo wh trigger
Cet outil interactif vous permet de sélectionner parmi les 22 types d’événements pris en charge et envoie des payloads réalistes simulés vers votre endpoint. Il boucle pour que vous puissiez tester plusieurs événements dans une seule session.
Les payloads webhook simulés provenant de dodo wh trigger ne sont pas signés. Utilisez unsafe_unwrap() au lieu de unwrap() dans votre gestionnaire webhook uniquement pendant les tests.

CLI Webhook Testing Docs

Consultez la documentation complète de test des webhooks CLI

Paramètres avancés

L’onglet Paramètres avancés propose des options de configuration supplémentaires pour affiner le comportement de votre endpoint webhook.

Limitation du débit (throttling)

Contrôlez le rythme de livraison des événements webhook vers votre endpoint pour éviter de surcharger votre système.
1

Access Rate Limit Settings

Dans l’onglet Advanced, localisez la section « Rate Limit (throttling) ».
2

Configure Rate Limit

Cliquez sur le bouton Edit pour modifier les paramètres de limitation de débit.
Par défaut, les webhooks ont « No rate limit », ce qui signifie que les événements sont livrés dès qu’ils se produisent.
3

Set Limits

Configurez votre limitation de débit souhaitée pour contrôler la fréquence de livraison des webhooks et éviter la surcharge du système.
Utilisez la limitation de débit lorsque votre gestionnaire webhook a besoin de temps pour traiter les événements ou lorsque vous souhaitez regrouper plusieurs événements.

En-têtes personnalisés

Ajoutez des en-têtes HTTP personnalisés à toutes les requêtes webhook envoyées à votre endpoint. Cela est utile pour l’authentification, le routage ou l’ajout de métadonnées à vos requêtes webhook.
1

Add Custom Header

Dans la section « Custom Headers », saisissez une Key et une Value pour votre en-tête personnalisé.
2

Add Multiple Headers

Cliquez sur le bouton + pour ajouter d’autres en-têtes personnalisés selon vos besoins.
3

Save Configuration

Vos en-têtes personnalisés seront inclus dans toutes les requêtes webhook vers cet endpoint.

Transformations

Les transformations vous permettent de modifier le payload d’un webhook et de le rediriger vers une URL différente. Cette fonctionnalité puissante vous permet de :
  • Modifier la structure du payload avant traitement
  • Router les webhooks vers différents endpoints en fonction du contenu
  • Ajouter ou supprimer des champs du payload
  • Transformer les formats de données
1

Enable Transformations

Basculez l’interrupteur Enabled pour activer la fonctionnalité de transformation.
2

Configure Transformation

Cliquez sur Edit transformation pour définir vos règles de transformation.
Vous pouvez utiliser JavaScript pour transformer le payload webhook et spécifier une URL cible différente.
3

Test Transformation

Utilisez l’interface de test pour vérifier que votre transformation fonctionne correctement avant la mise en production.
Les transformations peuvent avoir un impact significatif sur les performances de livraison des webhooks. Testez-les rigoureusement et gardez la logique de transformation simple et efficace.
Les transformations sont particulièrement utiles pour :
  • Convertir entre différents formats de données
  • Filtrer les événements selon des critères spécifiques
  • Ajouter des champs calculés au payload
  • Router les événements vers différents microservices

Surveillance des journaux de webhooks

L’onglet Logs offre une visibilité complète sur l’état de livraison de vos webhooks, vous permettant de surveiller, déboguer et gérer efficacement les événements webhook.
Logs

Surveillance de l’activité

L’onglet Activity fournit des informations en temps réel sur les performances de livraison de vos webhooks avec des analyses visuelles.
Activity

Alertes par e-mail

Restez informé de la santé de vos webhooks grâce à des notifications par e-mail automatiques. Lorsque les livraisons de webhooks commencent à échouer ou que votre endpoint cesse de répondre, vous recevrez des alertes par e-mail afin de pouvoir résoudre rapidement les problèmes et maintenir vos intégrations en bon fonctionnement.
Webhook Alerting Settings showing email notifications configuration

Activer les alertes par e-mail

1

Navigate to Alerting Settings

Rendez-vous sur votre tableau de bord Dodo Payments et naviguez vers Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Activez Email notifications pour commencer à recevoir des alertes concernant les problèmes de livraison des webhooks.
3

Configure Email Address

Saisissez l’adresse e-mail à laquelle vous souhaitez recevoir les alertes de webhook. Nous enverrons des notifications à cette adresse lorsqu’un certain nombre d’événements liés à votre configuration webhook se produira, comme des problèmes de livraison pouvant affecter vos intégrations.
Activez les alertes par e-mail pour détecter rapidement les problèmes de livraison des webhooks et maintenir des intégrations fiables. Vous serez averti lorsque les livraisons échouent ou que votre endpoint devient non réactif.

Déploiement sur les plateformes cloud

Prêt à déployer votre gestionnaire de webhooks en production ? Nous fournissons des guides spécifiques aux plateformes pour vous aider à déployer des webhooks sur les fournisseurs cloud populaires avec les meilleures pratiques propres à chaque plateforme.
Chaque guide de plateforme inclut la configuration de l’environnement, la vérification des signatures et les étapes de déploiement spécifiques à ce fournisseur.