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.

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

Always use HTTPS URLs for webhook endpoints. HTTP endpoints are vulnerable to man-in-the-middle attacks and expose your webhook data.
Return a 200 status code immediately upon receiving the webhook. Process the event asynchronously to avoid timeouts.
Implement idempotency using the webhook-id header to safely process the same event multiple times without side effects.
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

Headers

string
requis
Unique identifier for this webhook event. Use this for idempotency checks.
string
requis
HMAC SHA256 signature for verifying the webhook authenticity.
string
requis
Unix timestamp (in seconds) when the webhook was sent.

Request Body

string
requis
Your Dodo Payments business identifier.
string
requis
Event type that triggered this webhook (e.g., payment.succeeded, subscription.active).
string
requis
ISO 8601 formatted timestamp of when the event occurred.
object
requis
Event-specific payload containing detailed information about the event.

Example Payload

Event Types

Browse all available webhook event types

Event Payloads

View detailed payload schemas for each event

Handle Payment Failures

React to payment.failed and recover declined payments

Testing Webhooks

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

Navigate to Webhooks

Go to your Dodo Payments Dashboard and navigate to Developer → 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.

Send an Example Event

The Testing tab dispatches a sample payload to this endpoint so you can verify your receiver.
1

Select Event Type

Use Select an event type to choose the event you want to test, for example payment.succeeded or payment.failed.
2

Send Example

Click Send example. The sample payload is delivered to your endpoint URL exactly like a real event, signed the same way.
Failed messages sent from the Testing tab are not retried. Use it to verify your receiver, not to test the retry schedule.
3

Check Your Endpoint

The tab records when the Last example sent went out. Confirm the event arrived, that your signature verification passed, and that you returned a 2xx status code.

Implementation Example

Here’s a complete Express.js implementation showing webhook verification and handling:
Test your webhook handler thoroughly using the dashboard testing interface before processing production events. This helps identify and fix issues early.

Testing Webhooks with the CLI

The Dodo Payments CLI provides two commands for testing webhooks during local development, without needing to leave your terminal.

Listen for Live Webhooks Locally

Forward real webhook events from your test mode account to your local development server in real time:
The CLI opens a WebSocket connection to Dodo Payments and forwards every webhook event to your local endpoint (e.g., http://localhost:3000/webhook), preserving all headers including signature headers for verification testing.
The listener only works with test mode API keys. Run dodo login and select Test Mode before using this command.

Trigger Mock Webhook Events

Send mock webhook payloads to any endpoint without creating real transactions:
This interactive tool lets you pick an event type and sends a realistic mock payload to your endpoint. It loops so you can test multiple events in one session. The trigger command covers all 46 event types Dodo Payments delivers, including the subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, and entitlement grant families — see Supported Webhook Events for the exact list.
Mock webhook payloads from dodo wh trigger are not signed. Use unsafe_unwrap() instead of unwrap() in your webhook handler during testing only.

CLI Webhook Testing Docs

See the full CLI webhook testing documentation

Advanced Settings

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

Open Advanced Tab

From your endpoint details page, click the Advanced tab.
2

Configure Rate Limit

In the “Rate Limit (throttling)” section, click Edit 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 Your Limit

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

Add Headers

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

Add Multiple Headers

Click the + button to add additional custom headers as needed.
Your custom headers are included in all webhook requests to this endpoint.

Transformations

Transformations allow you to modify a webhook’s payload and optionally 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 using JavaScript.
3

Test Transformation

Use the transformation test interface to verify your transformation works correctly before going live.
Transformations can 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.
1

Navigate to Logs Tab

Go to Developer → Webhooks and open the Logs tab.
2

Browse Delivery History

View a table of all webhook delivery attempts with columns for Event type, Message ID, Event ID, Sent at, Attempted at, Response code, and Duration.
3

Search and Filter

Use the search bar to find specific messages by ID or event type. Filter by status (Succeeded, Failed, Pending, etc.) to focus on the events you need to investigate.
4

View Message Details

Click on any message to open the message detail page, which shows:
  • The complete webhook payload
  • Every delivery attempt with response code and duration
  • Timestamp of each attempt
  • Any error messages from your endpoint
Each attempt carries a Replay action, so you can re-drive that one message without leaving the page.

Activity Monitoring

Go to Developer → Webhooks and open the Activity tab for a view of delivery performance across your endpoints. Delivery activity plots attempts over time, bucketed as Attempts per 5 minutes, Attempts per hour, or Attempts per day depending on the window. Each bar is split by outcome, and hovering a segment shows the status, the number of attempts, and its share of the total. On an endpoint, Delivery stats (last 24h) on the Overview tab summarizes the same information for the past day.
The Error rate (24h) column on the Endpoints tab tells you at a glance which endpoints need attention, before you open any of them.

Replaying and Recovering Messages

How you re-drive a message depends on how many you need:
  • One message — open it from the Logs tab and use the Replay action on the attempt. No need to open the endpoint.
  • A range of messages — open the endpoint, since the bulk modes act on a single endpoint at a time.

Replaying in Bulk

Open the endpoint from Developer → Webhooks. Three modes are available, each acting on that endpoint alone. The range you set depends on the mode:
1

Open More Actions

On the endpoint, open More actions and pick one of the three modes above.
2

Set the Range

Fill in the range that mode asks for, as listed in the table.
3

Start the Run

Click Recover or Replay, depending on the mode you picked.
Every run appears under Replay history on the endpoint’s Overview tab, with its mode, time range, status, and the number of messages resent.

Email Alerts

Receive an email notification when webhook deliveries to an endpoint are failing, so you can address problems before they turn into a backlog.
1

Navigate to Settings Tab

Go to Developer → Webhooks and open the Settings tab.
2

Find Email Alerting

Locate the Email alerting card.
3

Configure Email Addresses

Enter the addresses that should receive the alerts. Separate multiple addresses with commas, and leave the field empty to turn alerts off.
4

Save

Click Save to apply your changes.
Enable email alerts to catch webhook delivery problems early and maintain reliable integrations.

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.

Create Webhook

API reference for creating and configuring webhook endpoints programmatically

List Webhooks

API reference for retrieving and managing your webhook endpoints
Dernière modification le 8 août 2026