Recevez des notifications en temps réel lorsque des événements se produisent dans Dodo Payments. Automatisez les flux de travail et maintenez vos systèmes synchronisés avec une livraison instantanée des événements.
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.
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.
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.
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.
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.
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.
Si une livraison de webhook échoue, Dodo Payments réessaie automatiquement avec un backoff exponentiel pour éviter de surcharger votre système.
Tentative
Délai
Description
1
Immédiatement
Le premier réessai se produit immédiatement
2
5 secondes
Deuxième tentative après un court délai
3
5 minutes
Troisième tentative avec un backoff accru
4
30 minutes
Quatrième tentative continuant le backoff
5
2 heures
Cinquième tentative avec un délai prolongé
6
5 heures
Sixième tentative avec un délai plus long
7
10 heures
Septième tentative avec un délai maximum
8
10 heures
Derniè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.
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.
Copier
// 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...});
Mettez toujours en œuvre des contrôles d’idempotence. En raison des relances, vous pouvez recevoir plusieurs fois le même événement.
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.
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.
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.
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.
Respond immediately
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.
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.
Secure your webhook secret
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.
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.
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.
Voici une implémentation complète en Express.js montrant la vérification et le traitement des webhooks :
Copier
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.
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 :
Copier
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.
Envoyez des payloads webhook simulés à n’importe quel endpoint sans créer de transactions réelles :
Copier
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.
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.
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.
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
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.
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.
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.
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.