Passer au contenu principal
Image de couverture Webhook
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.

Caractéristiques clés

Livraison en temps réel

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

Sécurisé par défaut

Vérification de la signature HMAC SHA256 incluse

Réessais automatiques

Logique de réessai intégrée avec un backoff exponentiel

Filtrage des événements

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

Commencer

1

Accéder aux paramètres des webhooks

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.
Ajouter un 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.

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

Naviguer vers les détails du webhook

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.

Gestion des abonnements d’événements

1

Voir les événements disponibles

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.

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 d’état 200, puis en gérant le traitement réel 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 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.

Idempotence

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.
// 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...
});
Implémentez toujours des vérifications d’idempotence. En raison des réessais, vous pouvez recevoir le même événement plusieurs fois.

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 le dernier payload au moment de la livraison, peu importe quand l’événement de 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 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.

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 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.
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 exact payload, séparés par des points (.).
  2. Calculez le HMAC SHA256 de cette chaîne en utilisant votre clé secrète de webhook du tableau de bord.
  3. Comparez la signature calculée à l’en-tête webhook-signature. Si elles correspondent, le webhook est authentique.
Nous suivons la spécification des Webhooks Standards. 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 payload d’événements, consultez le Payload de Webhook.

Répondre aux webhooks

  • Votre gestionnaire de webhook doit renvoyer un 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 réessayé.

Meilleures pratiques

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.
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.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
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.
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.

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
required
Identifiant unique pour cet événement de webhook. Utilisez ceci pour les vérifications d’idempotence.
webhook-signature
string
required
Signature HMAC SHA256 pour vérifier l’authenticité du webhook.
webhook-timestamp
string
required
Horodatage Unix (en secondes) lorsque le webhook a été envoyé.

Corps de la requête

business_id
string
required
Votre identifiant d’entreprise Dodo Payments.
type
string
required
Type d’événement qui a déclenché ce webhook (par exemple, payment.succeeded, subscription.created).
timestamp
string
required
Horodatage au format ISO 8601 de quand l’événement s’est produit.
data
object
required
Payload spécifique à l’événement contenant des informations détaillées sur l’événement.

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.
Détails du point de terminaison

Accéder à l’interface de test

1

Naviguer vers les webhooks

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

Sélectionner votre point de terminaison

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

Ouvrir l'onglet de test

Cliquez sur l’onglet Test 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

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.

Vérifier votre test

1

Vérifiez votre point de terminaison

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

Vérifier la signature

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

Tester la réponse

Confirmez que votre point de terminaison renvoie un code d’état 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.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.

Paramètres avancés

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

Limitation de débit (Throttling)

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.

En-têtes personnalisés

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.

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 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

Surveillance des journaux de webhook

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.
Journaux

Surveillance de l’activité

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

Alertes par e-mail

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.
Paramètres d'alerte de webhook montrant la configuration des notifications par e-mail

Activer les alertes par e-mail

1

Naviguer vers les paramètres d'alerte

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.

Déployer sur des plateformes cloud

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.