Webhook Cover Image

​
Introduction

This guide will walk you through setting up and securely handling webhooks. Our implementation follows the Standard Webhooks specification.

​
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.
You can create up to 5 webhook endpoints to receive notifications at different URLs or for different purposes.
3

Configure Endpoint

Enter the URL where you want to receive webhook events.
4

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

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

Merchants 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.
By default, webhook endpoints are configured to listen to all events. You can customize this to receive only the events relevant to your integration.
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, including both connection and read timeouts.
  • If a webhook delivery attempt fails, we will retry sending the event using exponential backoff to avoid overloading your system.

​
Retries

  • We will attempt a maximum of 8 retries for each failed webhook delivery.
  • Each retry follows a specific schedule based on the failure of the preceding attempt:
1

Retry Schedule

The retry attempts follow this schedule:
  • Immediately (first retry)
  • 5 seconds after the first failure
  • 5 minutes after the second failure
  • 30 minutes after the third failure
  • 2 hours after the fourth failure
  • 5 hours after the fifth failure
  • 10 hours after the sixth failure
  • 10 hours after the seventh failure (final retry)
2

Total Timeline

For example, if a webhook fails three times before succeeding, it will be delivered roughly 35 minutes and 5 seconds following the first attempt.
If a webhook endpoint is removed or disabled, all delivery attempts to that endpoint will be stopped immediately.
You can also use the Dodo Payments dashboard to manually retry each message at any time, or automatically retry (“Recover”) all failed messages.

​
Idempotency

  • Each webhook event contains a unique webhook-id header. Use this to implement idempotency and avoid processing the same event multiple times.
  • Even if you receive the same event more than once (due to retries), your system should handle it gracefully without causing errors or duplicate actions.

​
Ordering

  • Webhook delivery order is not guaranteed, as webhooks may be delivered out of order due to retries or network issues.
  • Ensure your system can handle events arriving out of order by using the webhook-id header to process events correctly.
Please note that you will receive the latest payload at the time of delivery, regardless of when the webhook event was 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. To verify a webhook came from DodoPayments:
  1. Compute the HMAC SHA256 of this string using your webhook secret key obtained from the DodoPayments Dashboard
  2. Concatenate the webhook-id, webhook-timestamp, and stringified payload values from the webhook with periods (.)
    The respective payloads for outgoing webhooks can be found in the Webhook Payload.
  3. Compare the computed signature to the received webhook-signature header value. If they match, the webhook is authentic.
Since we follow the Standard Webhooks specification, you can use one of their libraries to verify the signature: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries

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

​
Outgoing Webhook Payload Structure

The following section describes the structure of the outgoing webhook request sent to your endpoint. This helps you understand what to expect and how to parse the payload.

​
Endpoint

POST /your-webhook-url

​
Headers

​
webhook-id
string
required
Unique identifier for the webhook.
​
webhook-signature
string
required
Signature of the Webhook (HMAC SHA256).
​
webhook-timestamp
string
required
Unix timestamp when the webhook was sent.

​
Request Body

The request body is a JSON object with the following structure: 
{
  "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)
  }
}
For details on each event type, see the Webhook Event Type
For detailed payloads for each event type, see the Webhook Payload Event Guide

​
Responses

​
200
status code
Webhook processed successfully. You must return a 2xx status code to acknowledge receipt.
​
400
status code
Invalid request. The payload or headers are malformed.
​
401
status code
Invalid webhook signature. The signature verification failed.

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

​
Example code

An Express.js code snippet on how you can listen and verify our webhooks. 
// index.ts in express 
const { Webhook } = require("standardwebhooks");

const webhook = new Webhook('DODO_PAYMENTS_WEBHOOK_KEY');

// Add this endpoint in the Dodo Payments Website | Side Bar -> Developer -> Webhooks -> create
app.post('/webhook/dodo-payments', async (req: any, res: any) => {
  try {
    const body = req.body;

    const webhookHeaders: WebhookUnbrandedRequiredHeaders = {
      "webhook-id": (req.headers["webhook-id"] || "") as string,
      "webhook-signature": (req.headers["webhook-signature"] || "") as string,
      "webhook-timestamp": (req.headers["webhook-timestamp"] || "") as string,
    };

    const raw = JSON.stringify(body);

    const samePayloadOutput = await webhook.verify(raw, webhookHeaders);
    
    // ... Rest of your code HERE ...
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(400).json({ error: 'Webhook handler failed' });
  }
});
Use the testing interface to verify your webhook handler logic before processing real events. This helps catch issues early and ensures your integration is robust.

​
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.
We look forward to helping you implement seamless real-time notifications with webhooks! If you have any questions, please don’t hesitate to reach out to our support team.