Webhooks

Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.

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

1. Access Webhook Settings

   Navigate to the DodoPayments Dashboard and go to Settings > Webhooks.

2. Create Webhook Endpoint

   Click on Add Webhook to create a new webhook endpoint.

   
3. Add Endpoint URL

   Enter the URL where you want to receive webhook events.

4. Select Events to Receive

   Choose the specific events your webhook endpoint should listen for by selecting them from the event list.

   Only selected events will trigger webhooks to your endpoint, helping you avoid unnecessary traffic and processing.

5. Get Secret Key

   Obtain your webhook Secret Key from the settings page. 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.

6. Rotate Secret (Optional)

   If needed, you can rotate your webhook secret for enhanced security. Click the Rotate Secret button in your webhook settings.

   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.

Configuring Subscribed Events

You can configure which specific events they want to receive for each webhook endpoint.

Accessing Event Configuration

1. Navigate to Webhook Details

   Go to your Dodo Payments Dashboard and navigate to Settings > Webhooks.

2. Select Your Endpoint

   Click on the webhook endpoint you want to configure.

3. Open Event Settings

   In the webhook details page, you’ll see a “Subscribed events” section. Click the Edit button to modify your event subscriptions.

Managing Event Subscriptions

1. View Available Events

   The interface displays all available webhook events organized in a hierarchical structure. Events are grouped by category (e.g., dispute, payment, subscription).

2. Search and Filter

   Use the search bar to quickly find specific events by typing event names or keywords.

3. Select Events

   Check the boxes next to the events you want to receive. You can:

   • Select individual sub-events (e.g., dispute.accepted, dispute.challenged)
   • Select parent events to receive all related sub-events
   • Mix and match specific events based on your needs
4. Review Event Details

   Hover over the information icon (ⓘ) next to each event to see a description of when that event is triggered.

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

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.

Attempt	Delay	Description
1	Immediately	First retry happens right away
2	5 seconds	Second attempt after short delay
3	5 minutes	Third attempt with increased backoff
4	30 minutes	Fourth attempt continuing backoff
5	2 hours	Fifth attempt with extended delay
6	5 hours	Sixth attempt with longer delay
7	10 hours	Seventh attempt with maximum delay
8	10 hours	Final attempt - webhook marked as failed if unsuccessful

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.

// 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...
});

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.

SDK verification (recommended)

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.

TypeScript/Node.js

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' });
  }
});

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.

Responding to Webhooks

• Your webhook handler must return a 2xx status code to acknowledge receipt of the event.
• Any other response will be treated as a failure, and the webhook will be retried.

Best Practices

Use HTTPS endpoints only

Always use HTTPS URLs for webhook endpoints. HTTP endpoints are vulnerable to man-in-the-middle attacks and expose your webhook data.

Respond immediately

Return a 200 status code immediately upon receiving the webhook. Process the event asynchronously to avoid timeouts.

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

Handle duplicate events

Implement idempotency using the webhook-id header to safely process the same event multiple times without side effects.

Secure your webhook secret

Store your webhook secret securely using environment variables or a secrets manager. Never commit secrets to version control.

Webhook Payload Structure

Understanding the webhook payload structure helps you parse and process events correctly.

Request Format

POST /your-webhook-url
Content-Type: application/json

Headers

webhook-id · string · required

Unique identifier for this webhook event. Use this for idempotency checks.

webhook-signature · string · required

HMAC SHA256 signature for verifying the webhook authenticity.

webhook-timestamp · string · required

Unix timestamp (in seconds) when the webhook was sent.

Request Body

business_id · string · required

Your Dodo Payments business identifier.

type · string · required

Event type that triggered this webhook (e.g., payment.succeeded, subscription.created).

timestamp · string · required

ISO 8601 formatted timestamp of when the event occurred.

data · object · required

Event-specific payload containing detailed information about the event.

Show Data object properties

payload_type · string

Type of resource: Payment, Subscription, Refund, Dispute, or LicenseKey.

Additional fields vary by event type. See the event-specific documentation for complete schemas.

Example 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)
  }
}

Event Types

Browse all available webhook event types

Event Payloads

View detailed payload schemas for each event

Testing Webhooks

You can test your webhook integration directly from the Dodo Payments dashboard to ensure your endpoint is working correctly before going live.

Accessing the Testing Interface

1. Navigate to Webhooks

   Go to your Dodo Payments Dashboard and navigate to Settings > Webhooks.

2. Select Your Endpoint

   Click on your webhook endpoint to access its details page.

3. Open Testing Tab

   Click on the Testing tab to access the webhook testing interface.

Testing Your Webhook

The testing interface provides a comprehensive way to test your webhook endpoint:

1. Select Event Type

   Use the dropdown menu to select the specific event type you want to test (e.g., payment.succeeded, payment.failed, etc.).

   The dropdown contains all available webhook event types that your endpoint can receive.

2. Review Schema and Example

   The interface displays both the Schema (data structure) and Example (sample payload) for the selected event type.

3. Send Test Event

   Click the Send Example button to send a test webhook to your endpoint.

   Important: Failed messages sent through the testing interface will not be retried. This is for testing purposes only.

Verifying Your Test

1. Check Your Endpoint

   Monitor your webhook endpoint logs to confirm the test event was received.

2. Verify Signature

   Ensure your signature verification is working correctly with the test payload.

3. Test Response

   Confirm your endpoint returns a 2xx status code to acknowledge receipt.

Implementation Example

Here’s a complete Express.js implementation showing webhook verification and handling:

Express.js Webhook Handler

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

Test your webhook handler thoroughly using the dashboard testing interface before processing production events. This helps identify and fix issues early.

Advanced Settings

The Advanced Settings tab provides additional configuration options for fine-tuning your webhook endpoint behavior.

Rate Limiting (Throttling)

Control the rate at which webhook events are delivered to your endpoint to prevent overwhelming your system.

1. Access Rate Limit Settings

   In the Advanced tab, locate the “Rate Limit (throttling)” section.

2. Configure Rate Limit

   Click the Edit button to modify the rate limit settings.

   By default, webhooks have “No rate limit” applied, meaning events are delivered as soon as they occur.

3. Set Limits

   Configure your desired rate limit to control webhook delivery frequency and prevent system overload.

Use rate limiting when your webhook handler needs time to process events or when you want to batch multiple events together.

Custom Headers

Add custom HTTP headers to all webhook requests sent to your endpoint. This is useful for authentication, routing, or adding metadata to your webhook requests.

1. Add Custom Header

   In the “Custom Headers” section, enter a Key and Value for your custom header.

2. Add Multiple Headers

   Click the + button to add additional custom headers as needed.

3. Save Configuration

   Your custom headers will be included in all webhook requests to this endpoint.

Transformations

Transformations allow you to modify a webhook’s payload and redirect it to a different URL. This powerful feature enables you to:

• Modify the payload structure before processing
• Route webhooks to different endpoints based on content
• Add or remove fields from the payload
• Transform data formats

1. Enable Transformations

   Toggle the Enabled switch to activate the transformation feature.

2. Configure Transformation

   Click Edit transformation to define your transformation rules.

   You can use JavaScript to transform the webhook payload and specify a different target URL.

3. Test Transformation

   Use the testing interface to verify your transformation works correctly before going live.

Transformations can significantly impact webhook delivery performance. Test thoroughly and keep transformation logic simple and efficient.

Transformations are particularly useful for:

• Converting between different data formats
• Filtering events based on specific criteria
• Adding computed fields to the payload
• Routing events to different microservices

Monitoring Webhook Logs

The Logs tab provides comprehensive visibility into your webhook delivery status, allowing you to monitor, debug, and manage webhook events effectively.

Activity Monitoring

The Activity tab provides real-time insights into your webhook delivery performance with visual analytics.

Email Alerts

Stay informed about your webhook health with automatic email notifications. When webhook deliveries start failing or your endpoint stops responding, you’ll receive email alerts so you can quickly address issues and keep your integrations running smoothly.

Enable Email Alerts

1. Navigate to Alerting Settings

   Go to your Dodo Payments Dashboard and navigate to Dashboard → Webhooks → Alerting.

2. Enable Email Notifications

   Toggle on Email notifications to start receiving alerts about webhook delivery issues.

3. Configure Email Address

   Enter the email address where you want to receive webhook alerts. We’ll send notifications to this address when certain events occur with your webhooks setup, such as delivery issues that might affect your integrations.

Enable email alerts to catch webhook delivery problems early and maintain reliable integrations. You’ll be notified when deliveries fail or your endpoint becomes unresponsive.

Deploy to Cloud Platforms

Ready to deploy your webhook handler to production? We provide platform-specific guides to help you deploy webhooks to popular cloud providers with best practices for each platform.

Vercel

Deploy webhooks to Vercel with serverless functions

Cloudflare Workers

Run webhooks on Cloudflare’s edge network

Supabase Edge Functions

Integrate webhooks with Supabase

Netlify Functions

Deploy webhooks as Netlify serverless functions

Each platform guide includes environment setup, signature verification, and deployment steps specific to that provider.