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 des Webhooks Standards, garantissant la compatibilité avec les meilleures pratiques de l’industrie et les bibliothèques de webhooks existantes.
Accédez au tableau de bord DodoPayments et allez à Settings > Webhooks.
2
Créer un point de terminaison de webhook
Cliquez sur Add Webhook pour créer un nouveau point de terminaison de webhook.
3
Ajouter l'URL du point de terminaison
Entrez l’URL où vous souhaitez recevoir les événements de webhook.
4
Sélectionner les événements à recevoir
Choisissez les événements spécifiques auxquels votre point de terminaison de webhook doit s’abonner en les sélectionnant dans la liste des événements.
Seuls les événements sélectionnés déclencheront des webhooks vers votre point de terminaison, vous aidant à éviter un trafic et un traitement inutiles.
5
Obtenir la clé secrète
Obtenez votre Secret Key de la page des paramètres. Vous l’utiliserez pour vérifier l’authenticité des webhooks reçus.
Gardez votre clé secrète de webhook sécurisée et ne l’exposez jamais dans le code côté client ou dans des dépôts publics.
6
Faire tourner le secret (optionnel)
Si nécessaire, vous pouvez faire tourner votre secret de webhook pour une sécurité accrue. Cliquez sur le bouton Faire tourner le secret dans vos paramètres de webhook.
Faire tourner le secret le fera expirer et le remplacera par un nouveau. L’ancien secret ne sera valide que pour les 24 heures suivantes. Après cela, essayer de vérifier avec l’ancien secret échouera.
Utilisez la rotation des secrets périodiquement ou immédiatement si vous soupçonnez que votre secret actuel a été compromis.
Allez dans votre tableau de bord Dodo Payments et naviguez vers Settings > Webhooks.
2
Sélectionner votre point de terminaison
Cliquez sur le point de terminaison de webhook que vous souhaitez configurer.
3
Ouvrir les paramètres des événements
Dans la page des détails du webhook, vous verrez une section “Événements abonnés”. Cliquez sur le bouton Modifier pour modifier vos abonnements d’événements.
L’interface affiche tous les événements de webhook disponibles organisés dans une structure hiérarchique. Les événements sont regroupés par catégorie (par exemple, dispute, payment, subscription).
2
Rechercher et filtrer
Utilisez la barre de recherche pour trouver rapidement des événements spécifiques en tapant des noms d’événements ou des mots-clés.
3
Sélectionner des événements
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
Mélanger et assortir des événements spécifiques en fonction de vos besoins
4
Examiner les détails de l'événement
Survolez l’icône d’information (ⓘ) à côté de chaque événement pour voir une description de quand cet événement est déclenché.
5
Enregistrer la configuration
Cliquez sur Enregistrer pour appliquer vos modifications, ou Annuler pour annuler les modifications.
Si vous désélectionnez tous les événements, votre point de terminaison de webhook ne recevra aucune notification. Assurez-vous de 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 d’état 200, puis en gérant le traitement réel 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 réessai par événement de webhook. Par exemple, si un webhook échoue trois fois avant de réussir, le temps total de livraison est d’environ 35 minutes et 5 secondes depuis la première tentative.
Utilisez le tableau de bord Dodo Payments pour réessayer manuellement des messages individuels ou récupérer en masse tous les messages échoués à tout moment.
Chaque événement de webhook inclut un en-tête unique webhook-id. Utilisez cet identifiant pour mettre en œuvre l’idempotence et éviter le 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...});
Implémentez toujours des vérifications d’idempotence. En raison des réessais, vous pouvez recevoir le même événement plusieurs fois.
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 le dernier payload au moment de la livraison, peu importe quand l’événement de webhook a été émis à l’origine.
Chaque requête de webhook inclut un en-tête webhook-signature, une signature HMAC SHA256 du payload de 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 de webhook
unsafe_unwrap() : Analyse les payloads sans vérification
Fournissez votre secret de webhook via DODO_PAYMENTS_WEBHOOK_KEY lors de l’initialisation du client Dodo Payments.
Utiliser uniquement des points de terminaison HTTPS
Utilisez toujours des URL HTTPS pour les points de terminaison de webhook. Les points de terminaison HTTP sont vulnérables aux attaques de type homme du milieu et exposent vos données de webhook.
Répondre immédiatement
Retournez un code d’état 200 immédiatement après avoir reçu le webhook. Traitez l’événement de manière asynchrone pour éviter les délais d’attente.
Implémentez l’idempotence en utilisant l’en-tête webhook-id pour traiter en toute sécurité le même événement plusieurs fois sans effets secondaires.
Sécuriser votre clé secrète de webhook
Stockez votre clé secrète de webhook en toute sécurité en utilisant des variables d’environnement ou un gestionnaire de secrets. Ne jamais commettre de secrets dans le 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
Sélectionner le type d'événement
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 de webhook disponibles que votre point de terminaison peut recevoir.
2
Examiner le schéma et l'exemple
L’interface affiche à la fois le Schéma (structure des données) et l’Exemple (payload d’exemple) pour le type d’événement sélectionné.
3
Envoyer un événement de test
Cliquez sur le bouton Envoyer un exemple pour envoyer un test de webhook à votre point de terminaison.
Important : Les messages échoués envoyés via l’interface de test ne seront pas réessayé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.created': await handleSubscriptionCreated(data); break; // Add more event handlers... }}
Testez votre gestionnaire de webhook de manière approfondie en utilisant l’interface de test du tableau de bord avant de traiter des événements de production. Cela aide à identifier et à corriger les problèmes tôt.
L’onglet Paramètres avancés fournit des options de configuration supplémentaires pour affiner le comportement de votre point de terminaison de webhook.
Contrôlez le taux auquel les événements de webhook sont livrés à votre point de terminaison pour éviter de surcharger votre système.
1
Accéder aux paramètres de limitation de débit
Dans l’onglet Avancé, localisez la section “Limitation de débit (throttling)”.
2
Configurer la limitation de débit
Cliquez sur le bouton Modifier pour modifier les paramètres de limitation de débit.
Par défaut, les webhooks n’ont “Aucune limitation de débit” appliquée, ce qui signifie que les événements sont livrés dès qu’ils se produisent.
3
Définir les limites
Configurez votre limite 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 de webhook a besoin de temps pour traiter les événements ou lorsque vous souhaitez regrouper plusieurs événements ensemble.
Ajoutez des en-têtes HTTP personnalisés à toutes les requêtes de webhook envoyées à votre point de terminaison. Cela est utile pour l’authentification, le routage ou l’ajout de métadonnées à vos requêtes de webhook.
1
Ajouter un en-tête personnalisé
Dans la section “En-têtes personnalisés”, entrez une Clé et une Valeur pour votre en-tête personnalisé.
2
Ajouter plusieurs en-têtes
Cliquez sur le bouton + pour ajouter des en-têtes personnalisés supplémentaires si nécessaire.
3
Enregistrer la configuration
Vos en-têtes personnalisés seront inclus dans toutes les requêtes de webhook vers ce point de terminaison.
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 le traitement
Router les webhooks vers différents points de terminaison en fonction du contenu
Ajouter ou supprimer des champs du payload
Transformer les formats de données
1
Activer les transformations
Basculez l’interrupteur Activé pour activer la fonctionnalité de transformation.
2
Configurer la transformation
Cliquez sur Modifier la transformation pour définir vos règles de transformation.
Vous pouvez utiliser JavaScript pour transformer le payload de webhook et spécifier une URL cible différente.
3
Tester la transformation
Utilisez l’interface de test pour vérifier que votre transformation fonctionne correctement avant de passer en production.
Les transformations peuvent avoir un impact significatif sur les performances de livraison des webhooks. Testez soigneusement 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 en fonction de critères spécifiques
Ajouter des champs calculés au payload
Router les événements vers différents microservices
L’onglet Journaux fournit 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 de webhook.
Restez informé de la santé de vos webhooks avec des notifications par e-mail automatiques. Lorsque les livraisons de webhooks commencent à échouer ou que votre point de terminaison cesse de répondre, vous recevrez des alertes par e-mail afin que vous puissiez rapidement résoudre les problèmes et maintenir vos intégrations en bon état de fonctionnement.
Allez dans votre tableau de bord Dodo Payments et naviguez vers Tableau de bord → Webhooks → Alertes.
2
Activer les notifications par e-mail
Activez Notifications par e-mail pour commencer à recevoir des alertes concernant les problèmes de livraison de webhooks.
3
Configurer l'adresse e-mail
Entrez l’adresse e-mail où vous souhaitez recevoir les alertes de webhook. Nous enverrons des notifications à cette adresse lorsque certains événements se produisent avec votre configuration de webhooks, tels que des problèmes de livraison qui pourraient affecter vos intégrations.
Activez les alertes par e-mail pour détecter rapidement les problèmes de livraison de webhooks et maintenir des intégrations fiables. Vous serez informé lorsque les livraisons échouent ou que votre point de terminaison devient non réactif.
Prêt à déployer votre gestionnaire de webhook en production ? Nous fournissons des guides spécifiques à chaque plateforme pour vous aider à déployer des webhooks sur des fournisseurs cloud populaires avec les meilleures pratiques pour chaque plateforme.
Chaque guide de plateforme comprend la configuration de l’environnement, la vérification de la signature et les étapes de déploiement spécifiques à ce fournisseur.