
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
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
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 :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.Configuration des événements abonnés
Configurez les événements reçus par chaque endpoint webhook.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
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.Save Configuration
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
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’état200, 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 :Idempotence
Chaque webhook inclut un en-têtewebhook-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.
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 champtimestamp ; 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êtewebhook-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éfinissezDODO_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.
unwrap / unsafeUnwrap en TypeScript, unwrap / unsafe_unwrap en Python, et Unwrap / UnsafeUnwrap en Go.
Vérification manuelle (alternative)
Si vous n’utilisez pas de SDK, vérifiez vous-même la signature :- Construisez le contenu signé en joignant
webhook-id,webhook-timestampet 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. - 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. - Calculez le HMAC-SHA256 du contenu signé avec la clé de signature, puis encodez le résultat en base64.
- L’en-tête
webhook-signaturecontient une ou plusieurs signatures séparées par des espaces, chacune au formatv1,<base64-signature>. La requête est valide si une signaturev1correspond à la vôtre. Comparez-les avec une fonction à temps constant. - Rejetez la requête si
webhook-timestampest trop éloigné de l’heure actuelle, afin d’empêcher les attaques par rejeu. Les bibliothèques Standard Webhooks autorisent 5 minutes.
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êtewebhook-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.
Réponse aux webhooks
Votre gestionnaire de webhook doit renvoyer un2xx 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-idpour détecter et ignorer les événements en double. - Protégez votre secret. Stockez
DODO_PAYMENTS_WEBHOOK_KEYdans 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
Corps de la requête
payment.succeeded, subscription.active).Exemple de charge utile
Event Types
Event Payloads
Handle Payment Failures
payment.failed et récupérer les paiements refusésTester les webhooks
Envoyer un exemple d’événement
Testez votre intégration de webhook directement depuis le tableau de bord :Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Exemple d’implémentation
Implémentation Express.js complète avec vérification et traitement des webhooks :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 :http://localhost:3000/webhook), en conservant tous les en-têtes pour tester la vérification des signatures.
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 :subscription.past_due ni subscription.unpaused. Consultez Événements webhook pris en charge pour obtenir la liste exacte.
CLI Webhook Testing Docs
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.Open Advanced Tab
Configure Rate Limit
Set Your Limit
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.Add Headers
Add Multiple Headers
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
Enable Transformations
Configure Transformation
handler().Test Transformation
Surveiller les journaux des webhooks
L’onglet Logs fournit une visibilité sur l’état de livraison de vos webhooks.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 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
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.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 :Open More Actions
Set the Range
Start the Run