Skip to main content
Webhook Cover Image
Les webhooks fournissent des notifications en temps réel lorsque des événements se produisent dans votre compte Dodo Payments. Utilisez-les pour automatiser les workflows, mettre à jour votre base de données, envoyer des notifications et maintenir vos systèmes synchronisés.
Les webhooks Dodo Payments suivent la spécification Standard Webhooks pour la vérification des signatures et la structure des payloads.

Key Features

Les webhooks assurent une livraison en temps réel avec une sécurité intégrée, des nouvelles tentatives automatiques et un filtrage des événements. Tous les SDK officiels incluent des helpers de vérification des signatures, et le dashboard propose des outils de test, de surveillance et de rejeu.

Getting Started

1

Go to Developer → Webhooks

Dans le Dodo Payments Dashboard, accédez à Developer → Webhooks.
2

Click Add Endpoint

Cliquez sur Add endpoint pour créer un nouveau récepteur de webhook.
3

Enter Your Endpoint URL

Indiquez l’URL HTTPS à laquelle Dodo Payments enverra les événements webhook, ou sélectionnez un connecteur d’intégration (Slack, Discord, Zapier, Resend, etc.) pour acheminer les événements vers un service tiers sans écrire de code.
4

Select Events

Choisissez les événements à recevoir. Les événements sont organisés par ressource (payment, subscription, dispute, etc.). Vous pouvez sélectionner des événements individuels ou une ressource entière pour recevoir tous les événements associés.
5

Save

Cliquez sur Create endpoint. Votre secret de signature webhook apparaît dans l’onglet Overview de l’endpoint.
Conservez votre secret webhook en lieu sûr. Ne l’exposez jamais dans du code côté client ni dans le contrôle de version.
Pour faire pivoter votre secret webhook, ouvrez l’endpoint et cliquez sur Rotate secret à côté du secret dans l’onglet Overview. L’ancien secret reste valide pendant 24 heures après la rotation.

Connecteurs d’intégration

Acheminez directement les événements webhook vers des services tiers à l’aide de connecteurs d’intégration, sans avoir à créer et maintenir des gestionnaires de webhooks personnalisés.

Fonctionnement des connecteurs

Un connecteur transforme les événements Dodo Payments au format attendu par la destination. Les informations à fournir dépendent de la destination : Le dashboard affiche tous les connecteurs disponibles pour votre entreprise. Consultez External Integrations pour découvrir ce que chaque destination peut faire avec les événements.

Configuration d’un connecteur

Lors de la création ou de la modification d’un endpoint, sélectionnez un connecteur. Le panneau latéral affiche alors les instructions de configuration pour cette destination. Testez la transformation avant l’enregistrement afin de confirmer que les événements sont correctement convertis.
Utilisez un connecteur pour atteindre une destination prise en charge sans écrire de code. Si vous avez besoin d’une logique personnalisée, utilisez un endpoint standard avec une transformation.

Configuration des événements abonnés

Configurez les événements reçus par chaque endpoint webhook.
1

Navigate to Webhook Endpoints

Accédez à Developer → Webhooks et cliquez sur votre endpoint.
2

Open Event Configuration

Cliquez sur Edit pour ouvrir le panneau latéral de configuration de l’endpoint.
3

Select Events

Le sélecteur de types d’événements affiche tous les événements webhook disponibles dans un arbre consultable, regroupés par ressource (par exemple, payment, subscription, dispute). Cochez les cases des événements que vous souhaitez recevoir. Vous pouvez sélectionner des événements individuels, une ressource entière, ou combiner les deux.
4

Save Configuration

Cliquez sur Save pour appliquer vos modifications.
Si vous désélectionnez tous les événements, votre endpoint webhook reçoit tous les types d’événements. Sélectionnez uniquement les événements nécessaires à votre application.

Catalogue des événements

Accédez à Developer → Webhooks et ouvrez l’onglet Event catalog pour voir tous les types d’événements que Dodo Payments peut envoyer. Sélectionnez un événement pour afficher son schéma et un exemple de payload.

Webhook Events Guide

Consultez les événements comme documentation de référence, regroupés par ressource.

Livraison des webhooks

Délais d’expiration

Les webhooks ont un délai d’expiration de 30 secondes pour les opérations de connexion et de lecture. Traitez les webhooks de manière asynchrone en renvoyant immédiatement un code d’état 200, puis traitez l’événement en arrière-plan.

Nouvelle tentative automatique

Les livraisons échouées font l’objet de nouvelles tentatives avec un délai exponentiel, jusqu’à 8 tentatives au total : Utilisez le tableau de bord pour relancer manuellement les messages échoués ou récupérer en masse les messages d’une période donnée.

Idempotence

Chaque webhook inclut un en-tête webhook-id unique. Enregistrez cet identifiant pour détecter et ignorer les événements en double, car les nouvelles tentatives peuvent transmettre plusieurs fois le même événement.
Implémentez toujours des vérifications d’idempotence. En raison des nouvelles tentatives, vous pouvez recevoir plusieurs fois le même événement.

Ordre des événements

Les événements peuvent arriver dans le désordre en raison des nouvelles tentatives ou des conditions réseau. Chaque webhook inclut un champ timestamp ; utilisez-le pour ordonner les événements si votre application l’exige. Vous recevez toujours l’état le plus récent de la charge utile au moment de la livraison.

Sécurisation des webhooks

Validez toujours les charges utiles des webhooks et utilisez HTTPS.

Vérification des signatures

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

Vérification avec le SDK (recommandée)

Tous les SDK officiels incluent des fonctions d’aide intégrées. Définissez DODO_PAYMENTS_WEBHOOK_KEY lors de l’initialisation du client, puis appelez unwrap() pour vérifier et analyser la charge utile. Deux méthodes sont disponibles :
  • unwrap — Vérifie la signature avec votre clé secrète de webhook, puis analyse la charge utile.
  • unsafe_unwrap — Analyse la charge utile sans la vérifier. Utilisez cette méthode uniquement pour les tests.
Les noms des méthodes suivent les conventions de chaque langage : unwrap / unsafeUnwrap en TypeScript, unwrap / unsafe_unwrap en Python, et Unwrap / UnsafeUnwrap en Go.
Fournissez votre secret de webhook via DODO_PAYMENTS_WEBHOOK_KEY lors de l’initialisation du client Dodo Payments.

Vérification manuelle (alternative)

Si vous n’utilisez pas de SDK, vérifiez vous-même la signature :
  1. Construisez le contenu signé en joignant webhook-id, webhook-timestamp et le corps brut de la requête avec des points : {id}.{timestamp}.{body}. Utilisez le corps brut exactement tel qu’il a été reçu, avant toute analyse JSON.
  2. Prenez votre secret de webhook. S’il commence par whsec_, supprimez ce préfixe, puis décodez le reste en base64 pour obtenir la clé de signature.
  3. Calculez le HMAC-SHA256 du contenu signé avec la clé de signature, puis encodez le résultat en base64.
  4. L’en-tête webhook-signature contient une ou plusieurs signatures séparées par des espaces, chacune au format v1,<base64-signature>. La requête est valide si une signature v1 correspond à la vôtre. Comparez-les avec une fonction à temps constant.
  5. Rejetez la requête si webhook-timestamp est trop éloigné de l’heure actuelle, afin d’empêcher les attaques par rejeu. Les bibliothèques Standard Webhooks autorisent 5 minutes.
Consultez les bibliothèques Standard Webhooks pour des implémentations de référence. Pour les formats des charges utiles d’événements, consultez la charge utile du webhook.

Adresses IP sources

La vérification de signature est la méthode d’authentification prise en charge. Elle prouve que la requête a été signée avec votre secret de webhook, ce qu’une vérification au niveau du réseau ne peut pas garantir. Les livraisons de webhooks proviennent d’un ensemble d’adresses IP qui évolue au fil du temps. Ne vous fiez pas aux listes d’autorisation IP pour l’authentification. Vérifiez toujours l’en-tête webhook-signature à la place, comme indiqué dans Vérification des signatures. Si votre pare-feu exige une liste d’autorisation :
  • Ne codez pas les adresses en dur de façon permanente. Les plages évoluent et les règles obsolètes bloquent silencieusement les livraisons.
  • Demandez les plages actuelles à support@dodopayments.com avant de verrouiller un pare-feu.
  • Surveillez les avis de modification. Lorsque les adresses de livraison changent, nous informons les marchands concernés par e-mail — appliquez les mises à jour avant la date indiquée.
  • Maintenez la vérification des signatures activée, quelles que soient les règles réseau que vous ajoutez.
Sur les plateformes serverless et d’hébergement géré, le filtrage des IP entrantes est souvent indisponible ou peu pratique. La vérification des signatures est le contrôle approprié dans ces environnements.
Une livraison bloquée est considérée comme un échec et fait l’objet de nouvelles tentatives selon le calendrier décrit dans Nouvelle tentative automatique. Si des règles de pare-feu ont entraîné l’échec des livraisons, vous pouvez les renvoyer une fois les règles corrigées — consultez Relance et récupération des messages.

Réponse aux webhooks

Votre gestionnaire de webhook doit renvoyer un 2xx status code pour confirmer la réception. Toute autre réponse est considérée comme un échec et le webhook fera l’objet d’une nouvelle tentative.

Bonnes pratiques

  • Utilisez uniquement HTTPS. Les points de terminaison HTTP sont vulnérables à l’interception.
  • Répondez immédiatement. Renvoyez immédiatement un code d’état 200, puis traitez l’événement de manière asynchrone.
  • Implémentez l’idempotence. Utilisez l’en-tête webhook-id pour détecter et ignorer les événements en double.
  • Protégez votre secret. Stockez DODO_PAYMENTS_WEBHOOK_KEY dans des variables d’environnement ou un gestionnaire de secrets, jamais dans le contrôle de version.

Structure de la charge utile d’un webhook

Format de la requête

En-têtes

string
requis
Identifiant unique de cet événement webhook. À utiliser pour les vérifications d’idempotence.
string
requis
Signature HMAC SHA256 permettant de vérifier l’authenticité du webhook.
string
requis
Horodatage Unix (en secondes) auquel le webhook a été envoyé.

Corps de la requête

string
requis
Identifiant de votre entreprise Dodo Payments.
string
requis
Type d’événement ayant déclenché ce webhook (par exemple, payment.succeeded, subscription.active).
string
requis
Horodatage au format ISO 8601 du moment où l’événement s’est produit.
object
requis
Charge utile propre à l’événement contenant des informations détaillées sur celui-ci.

Exemple de charge utile

Event Types

Parcourir tous les types d’événements webhook disponibles

Event Payloads

Afficher les schémas détaillés des charges utiles pour chaque événement

Handle Payment Failures

Réagir à payment.failed et récupérer les paiements refusés

Tester les webhooks

Envoyer un exemple d’événement

Testez votre intégration de webhook directement depuis le tableau de bord :
1

Navigate to Webhooks

Accédez à Developer → Webhooks et cliquez sur votre point de terminaison.
2

Open Testing Tab

Cliquez sur l’onglet Testing.
3

Send Example

Sélectionnez un type d’événement et cliquez sur Send example. La charge utile d’exemple est envoyée à l’URL de votre point de terminaison exactement comme un événement réel, avec la même signature.
4

Check Your Endpoint

Confirmez que l’événement est arrivé, que la vérification de signature a réussi et que vous avez renvoyé un code d’état 2xx.
Les messages échoués envoyés depuis l’onglet Testing font l’objet de nouvelles tentatives selon le calendrier normal, comme tout autre webhook.

Exemple d’implémentation

Implémentation Express.js complète avec vérification et traitement des webhooks :
Testez soigneusement votre gestionnaire de webhook à l’aide de l’interface de test du tableau de bord avant de traiter les événements de production. Cela permet d’identifier et de corriger les problèmes rapidement.

Tester les webhooks avec la CLI

La Dodo Payments CLI propose deux commandes pour tester les webhooks pendant le développement local.

Écouter les webhooks en direct localement

Transférez les événements webhook réels de votre compte en mode test vers votre serveur de développement local :
La CLI ouvre une connexion WebSocket et transfère chaque événement webhook vers votre point de terminaison local (par exemple, http://localhost:3000/webhook), en conservant tous les en-têtes pour tester la vérification des signatures.
L’écouteur ne fonctionne qu’avec des clés API en mode test. Exécutez dodo login et sélectionnez d’abord Test Mode.

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

Envoyez des charges utiles webhook simulées vers n’importe quel point de terminaison sans créer de transactions réelles :
Cet outil interactif vous permet de choisir un type d’événement et d’envoyer une charge utile simulée réaliste vers votre point de terminaison. Il fonctionne en boucle afin que vous puissiez tester plusieurs événements au cours d’une même session. La commande de déclenchement couvre les familles d’événements suivantes : abonnement, paiement, remboursement, litige, clé de licence, versement, crédit, panier abandonné, recouvrement et attribution de droits. Elle n’envoie pas subscription.past_due ni subscription.unpaused. Consultez Événements webhook pris en charge pour obtenir la liste exacte.
Les charges utiles webhook simulées provenant de dodo wh trigger ne sont pas signées. Utilisez la méthode d’analyse non vérifiée (unsafeUnwrap en TypeScript, unsafe_unwrap en Python, UnsafeUnwrap en Go) dans votre gestionnaire de webhook uniquement pendant les tests.

CLI Webhook Testing Docs

Consultez la documentation complète sur les tests de webhooks avec la CLI

Paramètres avancés

L’onglet Advanced fournit des options de configuration supplémentaires pour ajuster le comportement de votre point de terminaison webhook.

Limitation du débit (throttling)

Contrôlez la vitesse à laquelle les événements webhook sont livrés à votre point de terminaison. Par défaut, les webhooks ne sont soumis à aucune limite de débit et les événements sont livrés dès qu’ils se produisent.
1

Open Advanced Tab

Depuis la page des détails de votre point de terminaison, cliquez sur l’onglet Advanced.
2

Configure Rate Limit

Développez la section Endpoint throttling.
3

Set Your Limit

Saisissez le nombre maximal de messages par seconde, puis cliquez sur Save. Les livraisons dépassant cette limite sont mises en file d’attente plutôt que supprimées.

En-têtes personnalisés

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

Add Headers

Dans la section Custom headers, saisissez un nom et une valeur d’en-tête.
2

Add Multiple Headers

Cliquez sur Add header pour chaque en-tête supplémentaire, puis cliquez sur Save.

Transformations

Les transformations vous permettent de modifier la charge utile d’un webhook et éventuellement de le rediriger vers une autre URL. Utilisez les transformations pour :
  • Modifier la structure de la charge utile avant le traitement
  • Acheminer les webhooks vers différents points de terminaison selon leur contenu
  • Ajouter ou supprimer des champs de la charge utile
  • Transformer les formats de données
1

Enable Transformations

Dans la section Transformation, activez Enable transformation.
2

Configure Transformation

Écrivez vos règles de transformation en JavaScript dans l’éditeur de code, puis cliquez sur Save. Le code doit renvoyer l’objet webhook depuis handler().
3

Test Transformation

Utilisez l’interface de test des transformations pour vérifier leur bon fonctionnement avant la mise en production.
Les transformations peuvent affecter les performances de livraison des webhooks. Testez-les soigneusement et gardez la logique de transformation simple et efficace.

Surveiller les journaux des webhooks

L’onglet Logs fournit une visibilité sur l’état de livraison de vos webhooks.
1

Navigate to Logs Tab

Accédez à Developer → Webhooks et ouvrez l’onglet Logs.
2

Browse Delivery History

Affichez un tableau de toutes les tentatives de livraison de webhook, avec les colonnes Type d’événement, ID du message, ID de l’événement, Envoyé à, Tentative à, Code de réponse et Durée.
3

Search and Filter

Utilisez la barre de recherche pour trouver des messages spécifiques par ID ou type d’événement. Filtrez par état (Succeeded, Failed, Pending, etc.) pour vous concentrer sur les événements à examiner.
4

View Message Details

Cliquez sur un message pour ouvrir sa page de détails, qui affiche :
  • La charge utile complète du webhook
  • Chaque tentative de livraison avec son code de réponse et sa durée
  • L’horodatage de chaque tentative
  • Les éventuels messages d’erreur provenant de votre point de terminaison
Chaque tentative comporte une action Replay permettant de relancer ce message sans quitter la page.

Surveillance de l’activité

Accédez à Developer → Webhooks et ouvrez l’onglet Activity pour voir les performances de livraison sur l’ensemble de vos points de terminaison. Delivery activity représente les tentatives au fil du temps, regroupées sous Attempts per 5 minutes, Attempts per hour ou Attempts per day selon la période. Chaque barre est divisée selon le résultat ; passez la souris sur un segment pour afficher l’état, le nombre de tentatives et sa part du total. Sur un point de terminaison, Delivery stats (last 24h) dans l’onglet Overview récapitule les mêmes informations pour la journée écoulée.
La colonne Error rate (24h) de l’onglet Endpoints indique d’un coup d’œil les points de terminaison nécessitant une intervention.

Relance et récupération des messages

La manière de relancer un message dépend du nombre de messages concernés :
  • Un message — ouvrez-le depuis l’onglet Logs et utilisez l’action Replay sur la tentative.
  • Une plage de messages — ouvrez le point de terminaison, car les modes groupés agissent sur un seul point de terminaison à la fois.

Relance en masse

Ouvrez le point de terminaison depuis Developer → Webhooks. Trois modes sont disponibles, chacun agissant uniquement sur ce point de terminaison :
1

Open More Actions

Sur le point de terminaison, ouvrez More actions et choisissez l’un des trois modes ci-dessus.
2

Set the Range

Renseignez la période demandée par le mode, comme indiqué dans le tableau.
3

Start the Run

Cliquez sur Recover ou Replay, selon le mode choisi.
Chaque exécution apparaît sous Replay history dans l’onglet Overview du point de terminaison, avec son mode, sa période, son état et le nombre de messages renvoyés.

Alertes par e-mail

Le tableau de bord des webhooks ne propose pas d’alertes par e-mail pour les livraisons échouées. Pour surveiller les livraisons, accédez à Developer → Webhooks et consultez les onglets Logs et Activity.

Déployer sur des plateformes cloud

Guides spécifiques aux plateformes pour déployer des gestionnaires de webhooks chez des fournisseurs cloud populaires :

Vercel

Déployer des webhooks sur Vercel avec des fonctions serverless

Cloudflare Workers

Exécuter des webhooks sur le réseau edge de Cloudflare

Supabase Edge Functions

Intégrer des webhooks avec Supabase

Netlify Functions

Déployer des webhooks comme fonctions serverless Netlify

Référence API associée

Create Webhook

Créer et configurer des points de terminaison webhook par programmation

List Webhooks

Récupérer et gérer vos points de terminaison webhook
Dernière modification le 28 septembre 2026