Skip to main content
Webhook Cover Image
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

The Dodo Payments webhooks portal has been rebuilt with a native dashboard experience. Your existing endpoints, signing secrets, signature verification, event names, and webhook payloads are unchanged. No integration work is needed.
Where things live.
  • Under Developer → Webhooks — the Endpoints, Event catalog, Logs, Activity, and Settings tabs.
  • On an individual endpoint — the Overview tab, carrying delivery stats, the signing secret and Replay history, plus the Testing and Advanced tabs and the bulk replay actions.
  • On a message — opened from the Logs tab, where each delivery attempt can be replayed on its own without opening the endpoint.
1

Access Webhook Settings

Navigate to the Dodo Payments Dashboard and go to Developer → Webhooks.
2

Create Webhook Endpoint

Click Add endpoint to open the endpoint creation side sheet.
3

Enter Endpoint URL or Choose Integration

Enter the URL where you want to receive webhook events, or select an integration connector to route events to a third-party service (Slack, Discord, Zapier, Resend, etc.).
4

Select Events to Receive

Choose the specific events your endpoint should listen for. Events are organized in a searchable tree grouped by resource. You can select individual events or a parent resource to receive all related events.
Only selected events will trigger webhooks to your endpoint, helping you avoid unnecessary traffic and processing.
5

Create Endpoint

Click Create endpoint to save your configuration.
6

Get Secret Key

Your webhook signing secret is displayed on the endpoint’s Overview tab. You’ll use this to verify the authenticity of received webhooks.
Keep your webhook secret key secure and never expose it in client-side code or public repositories.
7

Rotate Secret (Optional)

If needed, you can rotate your webhook secret for enhanced security. Click Rotate secret, alongside the secret on the Overview tab.
Rotating the secret will expire it and replace it with a new one. The old secret will only be valid for the next 24 hours. Afterward, trying to verify with the old secret will fail.
Use secret rotation periodically or immediately if you suspect your current secret has been compromised.

Integration Connectors

Instead of building your own webhook receiver, you can route webhook events directly to third-party services using integration connectors. This eliminates the need to write and maintain custom webhook handlers for popular platforms.

How Connectors Work

A connector carries a transformation that converts the Dodo Payments event into the shape the destination expects. Which details you supply depends on the destination: The connector picker in the dashboard shows the full set currently available to your business, so treat the table above as the destinations with step-by-step setup instructions rather than an exhaustive list. See External Integrations for what each destination can do once events reach it.

Setting Up a Connector

Pick a connector while creating or editing an endpoint, and the side sheet shows setup instructions written for that destination — for example, how to create an incoming webhook URL in Slack, or where to find your Resend API key. Before you save, run the connector transformation test to confirm the event is converted correctly for the destination.
Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a transformation instead.

Configuring Subscribed Events

You can configure which specific events each webhook endpoint should receive.
1

Navigate to Webhook Endpoints

Go to your Dodo Payments Dashboard and navigate to Developer → Webhooks.
2

Select Your Endpoint

Click on the webhook endpoint you want to configure.
3

Open Event Configuration

Click Edit to open the endpoint configuration side sheet.
4

Browse Event Types

The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., payment, subscription, dispute). Use the search bar to quickly find specific events by name or keyword.
5

Select Events

Check the boxes next to the events you want to receive. You can:
  • Select individual events (e.g., payment.succeeded, payment.failed)
  • Select a parent resource to receive all related events
  • Mix and match specific events based on your needs
6

Save Configuration

Click Save to apply your changes, or Cancel to discard modifications.
If you deselect all events, your webhook endpoint will not receive any notifications. Make sure to select at least the events your application needs to function properly.

Event Catalog

Go to Developer → Webhooks and open the Event catalog tab. It lists every event type Dodo Payments can send, so you can see what is available before subscribing an endpoint to it. Select an event to view its schema and an example payload, which is the quickest way to check the shape of a field you plan to read.

Webhook Events Guide

Browse the same events as reference documentation, grouped by resource.

Webhook Delivery

Timeouts

Webhooks have a 15-second timeout window for both connection and read operations. Ensure your endpoint responds quickly to avoid timeouts.
Process webhooks asynchronously by acknowledging receipt immediately with a 200 status code, then handling the actual processing in the background.

Automatic Retries

If a webhook delivery fails, Dodo Payments automatically retries with exponential backoff to prevent overwhelming your system.
Maximum of 8 retry attempts per webhook event. For example, if a webhook fails three times before succeeding, the total delivery time is approximately 35 minutes and 5 seconds from the first attempt.
Use the Dodo Payments dashboard to manually retry individual messages or bulk recover all failed messages at any time.

Idempotency

Each webhook event includes a unique webhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
Always implement idempotency checks. Due to retries, you may receive the same event multiple times.

Event Ordering

Webhook events may arrive out of order due to retries or network conditions. Design your system to handle events in any sequence.
You will receive the latest payload at the time of delivery, regardless of when the webhook event was originally emitted.

Securing Webhooks

To ensure the security of your webhooks, always validate the payloads and use HTTPS.

Verifying Signatures

Each webhook request includes a webhook-signature header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key. All official SDKs include built‑in helpers to securely validate and parse incoming webhooks. Two methods are available:
  • unwrap(): Verifies signatures using your webhook secret key
  • unsafe_unwrap(): Parses payloads without verification
Provide your webhook secret via DODO_PAYMENTS_WEBHOOK_KEY when initializing the Dodo Payments client.

Manual verification (alternative)

If you are not using an SDK, you can verify signatures yourself following the Standard Webhooks spec:
  1. Build the signed message by concatenating webhook-id, webhook-timestamp, and the exact raw stringified payload, separated by periods (.).
  2. Compute the HMAC SHA256 of that string using your webhook secret key from the Dashboard.
  3. Compare the computed signature to the webhook-signature header. If they match, the webhook is authentic.
We follow the Standard Webhooks specification. You can use their libraries to verify signatures: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. For event payload formats, see the Webhook Payload.

Adresses IP sources

La vérification de signature est la méthode prise en charge pour authentifier un webhook. 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 faire. Les livraisons de webhook sont envoyées depuis un pool d’adresses IP sources appartenant à notre infrastructure de livraison. Ce pool change de temps à autre ; considérez donc ces adresses comme un détail opérationnel plutôt que comme une propriété fixe de l’intégration.
N’utilisez pas une liste d’autorisation d’adresses IP sources comme mécanisme d’authentification. Une liste d’autorisation indique uniquement l’origine d’une requête, et non qu’elle est authentique ou n’a pas été modifiée — vérifiez l’en-tête webhook-signature sur chaque requête, comme décrit dans Vérification des signatures.
Si votre infrastructure se trouve derrière un firewall qui exige une liste d’autorisation explicite, gardez les points suivants à l’esprit :
  • Ne codez pas les adresses en dur de façon permanente. Des plages sont ajoutées et retirées au fil du temps, et une règle obsolète bloque silencieusement les livraisons.
  • Demandez les plages actuelles à support@dodopayments.com avant de verrouiller un firewall, afin de travailler à partir d’une liste à jour.
  • Surveillez les avis de changement. Lorsque les adresses de livraison changent, nous informons les marchands concernés par e-mail — appliquez ces mises à jour avant la date indiquée pour éviter les livraisons perdues.
  • Laissez la vérification de signature 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 à maintenir. La vérification de signature est le contrôle approprié dans ces environnements, et aucune liste d’autorisation n’est nécessaire.
Une livraison bloquée est traitée comme toute autre erreur et fait l’objet de nouvelles tentatives selon le calendrier décrit dans Nouvelles tentatives automatiques. Si des règles de firewall ont provoqué l’échec des livraisons, vous pouvez les renvoyer une fois les règles corrigées — consultez Rejouer et récupérer des messages.

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 fera l’objet d’une nouvelle tentative.

Bonnes pratiques

Utilisez toujours des URL HTTPS pour les endpoints de webhook. Les endpoints HTTP sont vulnérables aux attaques de type man-in-the-middle et exposent vos données de webhook.
Renvoyez immédiatement un code d’état 200 dès réception du webhook. Traitez l’événement de manière asynchrone afin d’éviter les timeouts.
Implémentez l’idempotence à l’aide de l’en-tête webhook-id afin de traiter plusieurs fois le même événement sans effets indésirables.
Stockez votre secret de webhook de manière sécurisée à l’aide de variables d’environnement ou d’un gestionnaire de secrets. Ne validez jamais 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 la requête

En-têtes

string
requis
Identifiant unique de cet événement webhook. Utilisez-le 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 à l’origine de ce webhook (par exemple, payment.succeeded, subscription.active).
string
requis
Horodatage au format ISO 8601 indiquant le moment où l’événement s’est produit.
object
requis
Payload propre à l’événement contenant des informations détaillées sur celui-ci.

Exemple de payload

Event Types

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

Event Payloads

Afficher les schémas de payload détaillés pour chaque événement

Handle Payment Failures

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

Tester les webhooks

Vous pouvez tester votre intégration de webhook directement depuis le tableau de bord Dodo Payments afin de vous assurer que votre endpoint fonctionne correctement avant sa mise en production.
1

Navigate to Webhooks

Accédez à votre tableau de bord Dodo Payments et ouvrez Developer → Webhooks.
2

Select Your Endpoint

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

Open Testing Tab

Cliquez sur l’onglet Testing pour accéder à l’interface de test des webhooks.

Envoyer un exemple d’événement

L’onglet Testing envoie un payload d’exemple à cet endpoint afin que vous puissiez vérifier votre récepteur.
1

Select Event Type

Utilisez Select an event type pour choisir l’événement à tester, par exemple payment.succeeded ou payment.failed.
2

Send Example

Cliquez sur Send example. Le payload d’exemple est livré à l’URL de votre endpoint exactement comme un événement réel, avec la même signature.
Les messages ayant échoué et envoyés depuis l’onglet Testing ne font pas l’objet de nouvelles tentatives. Utilisez cette fonction pour vérifier votre récepteur, et non pour tester le calendrier des nouvelles tentatives.
3

Check Your Endpoint

L’onglet indique quand le Last example sent a été envoyé. Vérifiez 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.

Exemple d’implémentation

Voici une implémentation complète avec Express.js montrant la vérification et le traitement des webhooks :
Testez soigneusement votre gestionnaire de webhook à l’aide de l’interface de test du tableau de bord avant de traiter des é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 fournit deux commandes pour tester les webhooks pendant le développement local, sans avoir à quitter votre terminal.

Écouter les webhooks en direct localement

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 :
La CLI ouvre une connexion WebSocket à Dodo Payments et transfère chaque événement webhook vers votre endpoint local (par exemple, http://localhost:3000/webhook), en conservant tous les en-têtes, y compris ceux de signature, pour tester la vérification.
Le listener fonctionne uniquement avec des clés API en test mode. Exécutez dodo login et sélectionnez Test Mode avant d’utiliser cette commande.

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

Envoyez des payloads webhook simulés vers n’importe quel endpoint sans créer de transactions réelles :
Cet outil interactif vous permet de choisir un type d’événement et d’envoyer un payload simulé réaliste vers votre endpoint. 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 47 types d’événements que Dodo Payments distribue, notamment les familles subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning et entitlement grant — consultez Événements webhook pris en charge pour obtenir la liste exacte.
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 de webhook, uniquement pendant les tests.

CLI Webhook Testing Docs

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

Paramètres avancés

L’onglet Advanced fournit des options de configuration supplémentaires pour ajuster précisément le comportement de votre endpoint de webhook.

Limitation du débit (throttling)

Contrôlez la fréquence à laquelle les événements webhook sont livrés à votre endpoint afin d’éviter de surcharger votre système.
1

Open Advanced Tab

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

Configure Rate Limit

Dans la section “Rate Limit (throttling)”, cliquez sur Edit pour modifier les paramètres de limitation du débit.
Par défaut, aucune limitation du débit ne s’applique aux webhooks : les événements sont donc livrés dès qu’ils se produisent.
3

Set Your Limit

Configurez la 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 du débit lorsque votre gestionnaire de webhook a besoin de temps pour traiter les événements ou lorsque vous souhaitez regrouper plusieurs événements.

En-têtes personnalisés

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

Add Headers

Dans la section “Custom Headers”, saisissez une Key et une Value pour chaque en-tête personnalisé.
2

Add Multiple Headers

Cliquez sur le bouton + pour ajouter d’autres en-têtes personnalisés si nécessaire.
Vos en-têtes personnalisés sont inclus dans toutes les requêtes webhook envoyées à cet endpoint.

Transformations

Les transformations vous permettent de modifier le payload d’un webhook et, si nécessaire, de le rediriger vers une autre URL. Cette fonctionnalité puissante vous permet de :
  • Modifier la structure du payload avant le traitement
  • Acheminer les webhooks vers différents endpoints en fonction de leur contenu
  • Ajouter ou supprimer des champs du payload
  • Transformer les formats de données
1

Enable Transformations

Activez le bouton Enabled pour activer la fonctionnalité de transformation.
2

Configure Transformation

Cliquez sur Edit transformation pour définir vos règles de transformation en JavaScript.
3

Test Transformation

Utilisez l’interface de test des transformations pour vérifier qu’elles fonctionnent correctement avant leur mise en production.
Les transformations peuvent affecter les performances de livraison des webhooks. Testez-les soigneusement et gardez leur logique simple et efficace.
Les transformations sont particulièrement utiles pour :
  • Convertir différents formats de données
  • Filtrer les événements selon des critères spécifiques
  • Ajouter des champs calculés au payload
  • Acheminer les événements vers différents microservices

Surveiller les journaux de webhook

L’onglet Logs offre une visibilité complète sur l’état de livraison de vos webhooks et vous permet de surveiller, déboguer et gérer efficacement les événements webhook.
1

Navigate to Logs Tab

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

Browse Delivery History

Consultez un tableau de toutes les tentatives de livraison de webhook, avec les colonnes Event type, Message ID, Event ID, Sent at, Attempted at, Response code et Duration.
3

Search and Filter

Utilisez la barre de recherche pour trouver des messages précis par ID ou type d’événement. Filtrez par statut (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 :
  • Le payload webhook complet
  • 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 endpoint
Chaque tentative comporte une action Replay, ce qui vous permet de relancer ce message sans quitter la page.

Surveillance de l’activité

Accédez à Developer → Webhooks et ouvrez l’onglet Activity pour consulter les performances de livraison de tous vos endpoints. Delivery activity représente les tentatives au fil du temps, regroupées par Attempts per 5 minutes, Attempts per hour ou Attempts per day selon la période. Chaque barre est répartie selon le résultat ; en survolant un segment, vous voyez le statut, le nombre de tentatives et sa part du total. Sur un endpoint, 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 immédiatement quels endpoints nécessitent votre attention, avant même que vous n’en ouvriez un.

Rejouer et récupérer 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. Il n’est pas nécessaire d’ouvrir l’endpoint.
  • Une plage de messages — ouvrez l’endpoint, car les modes groupés s’appliquent à un seul endpoint à la fois.

Rejouer en groupe

Ouvrez l’endpoint depuis Developer → Webhooks. Trois modes sont disponibles, chacun agissant uniquement sur cet endpoint. La plage à définir dépend du mode :
1

Open More Actions

Sur l’endpoint, ouvrez More actions et sélectionnez l’un des trois modes ci-dessus.
2

Set the Range

Saisissez la plage 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 de l’endpoint, avec son mode, sa période, son statut et le nombre de messages renvoyés.

Alertes par e-mail

Recevez une notification par e-mail lorsque les livraisons de webhook vers un endpoint échouent, afin de résoudre les problèmes avant qu’ils ne créent un backlog.
1

Navigate to Settings Tab

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

Find Email Alerting

Repérez la carte Email alerting.
3

Configure Email Addresses

Saisissez les adresses qui doivent recevoir les alertes. Séparez plusieurs adresses par des virgules et laissez le champ vide pour désactiver les alertes.
4

Save

Cliquez sur Save pour appliquer vos modifications.
Activez les alertes par e-mail pour détecter rapidement les problèmes de livraison des webhooks et maintenir des intégrations fiables.

Déployer sur des plateformes cloud

Prêt à déployer votre gestionnaire de webhook en production ? Nous fournissons des guides spécifiques aux plateformes pour vous aider à déployer des webhooks chez les principaux fournisseurs cloud, avec les bonnes pratiques propres à chaque plateforme.

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
Chaque guide de plateforme inclut la configuration de l’environnement, la vérification de signature et les étapes de déploiement propres au fournisseur concerné.

Référence API associée

Create Webhook

Référence API pour créer et configurer des endpoints de webhook par programmation

List Webhooks

Référence API pour récupérer et gérer vos endpoints de webhook
Dernière modification le 21 août 2026