Skip to main content
Webhook Cover Image
Webhooks deliver real-time notifications when events occur in your Dodo Payments account. Use them to automate workflows, update your database, send notifications, and keep your systems in sync.
Dodo Payments webhooks follow the Standard Webhooks specification for signature verification and payload structure.

Key Features

Webhooks provide real-time delivery with built-in security, automatic retries, and event filtering. All official SDKs include signature verification helpers, and the dashboard offers testing, monitoring, and replay tools.

Getting Started

1

Go to Developer → Webhooks

In the Dodo Payments Dashboard, navigate to Developer → Webhooks.
2

Click Add Endpoint

Click Add endpoint to create a new webhook receiver.
3

Enter Your Endpoint URL

Provide the HTTPS URL where Dodo Payments will send webhook events, or select an integration connector (Slack, Discord, Zapier, Resend, etc.) to route events to a third-party service without writing code.
4

Select Events

Choose which events to receive. Events are organized by resource (payment, subscription, dispute, etc.). You can select individual events or an entire resource to receive all related events.
5

Save

Click Create endpoint. Your webhook signing secret appears on the endpoint’s Overview tab.
Keep your webhook secret secure. Never expose it in client-side code or version control.
To rotate your webhook secret, open the endpoint and click Rotate secret next to the secret on the Overview tab. The old secret remains valid for 24 hours after rotation.

Integration Connectors

Route webhook events directly to third-party services using integration connectors, eliminating the need to build and maintain custom webhook handlers.

How Connectors Work

A connector transforms Dodo Payments events into the format the destination expects. Which details you provide depends on the destination: The dashboard shows all connectors available to your business. See External Integrations for what each destination can do with the events.

Setting Up a Connector

When creating or editing an endpoint, select a connector and the side sheet shows setup instructions for that destination. Test the transformation before saving to confirm events are converted correctly.
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

Configure which events each webhook endpoint receives.
1

Navigate to Webhook Endpoints

Go to Developer → Webhooks and click on your endpoint.
2

Open Event Configuration

Click Edit to open the endpoint configuration side sheet.
3

Select Events

The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., payment, subscription, dispute). Check the boxes next to the events you want to receive. You can select individual events, an entire resource, or mix and match.
4

Save Configuration

Click Save to apply your changes.
If you deselect all events, your webhook endpoint receives every event type. Select only the events your application needs.

Event Catalog

Go to Developer → Webhooks and open the Event catalog tab to see every event type Dodo Payments can send. Select an event to view its schema and sample payload.

Webhook Events Guide

Browse events as reference documentation, grouped by resource.

Webhook Delivery

Timeouts

Webhooks have a 30-second timeout for both connection and read operations. Process webhooks asynchronously by returning a 200 status code immediately, then handle the event in the background.

Automatic Retries

Failed deliveries are retried with exponential backoff, up to 8 attempts total: Use the dashboard to manually replay failed messages or bulk recover messages from a specific time range.

Idempotency

Each webhook includes a unique webhook-id header. Store this ID to detect and skip duplicate events, since retries may deliver the same event multiple times.
Always implement idempotency checks. Due to retries, you may receive the same event multiple times.

Event Ordering

Events may arrive out of order due to retries or network conditions. Each webhook includes a timestamp field; use it to order events if your application requires it. You always receive the latest payload state at delivery time.

Securing Webhooks

Always validate webhook payloads and use HTTPS.

Verifying Signatures

Each webhook includes a webhook-signature header: an HMAC SHA256 signature of the payload and timestamp, signed with your secret key. All official SDKs include built-in helpers. Set DODO_PAYMENTS_WEBHOOK_KEY when initializing the client, then call unwrap() to verify and parse the payload. Two methods are available:
  • unwrap — Verifies the signature with your webhook secret key, then parses the payload.
  • unsafe_unwrap — Parses the payload without verifying it. Use it for testing only.
The method names follow each language’s conventions: unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python, and Unwrap / UnsafeUnwrap in Go.
Provide your webhook secret via DODO_PAYMENTS_WEBHOOK_KEY when initializing the Dodo Payments client.

Manual Verification (Alternative)

If you’re not using an SDK, verify the signature yourself:
  1. Build the signed content by joining webhook-id, webhook-timestamp, and the raw request body with periods: {id}.{timestamp}.{body}. Use the raw body exactly as received, before any JSON parsing.
  2. Take your webhook secret. If it starts with whsec_, remove that prefix, then base64-decode the rest to get the signing key.
  3. Compute the HMAC-SHA256 of the signed content with the signing key, and base64-encode the result.
  4. The webhook-signature header holds one or more space-separated signatures, each in the form v1,<base64-signature>. The request is valid if any v1 signature matches yours. Compare with a constant-time function.
  5. Reject the request if webhook-timestamp is too far from the current time, to prevent replay attacks. The Standard Webhooks libraries allow 5 minutes.
See the Standard Webhooks libraries for reference implementations. For event payload formats, see the Webhook Payload.

Source IP Addresses

Signature verification is the supported authentication method. It proves the request was signed with your webhook secret, which a network-level check cannot do. Webhook deliveries come from a pool of IP addresses that changes over time. Do not rely on IP allowlists for authentication. Always verify the webhook-signature header instead, as described in Verifying Signatures. If your firewall requires an allowlist:
  • Do not hardcode addresses permanently. Ranges change over time, and stale rules silently block deliveries.
  • Request the current ranges from support@dodopayments.com before locking down a firewall.
  • Watch for change notices. When delivery addresses change, we notify affected merchants by email — apply updates before the stated date.
  • Keep signature verification enabled regardless of any network rules you add.
On serverless and managed hosting platforms, inbound IP filtering is often unavailable or impractical. Signature verification is the correct control in those environments.
A blocked delivery is treated as a failure and is retried on the schedule described in Automatic Retries. If firewall rules caused deliveries to fail, you can re-send them once the rules are fixed — see Replaying and Recovering Messages.

Responding to Webhooks

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

Best Practices

  • Use HTTPS only. HTTP endpoints are vulnerable to interception.
  • Respond immediately. Return a 200 status code right away, then process the event asynchronously.
  • Implement idempotency. Use the webhook-id header to detect and skip duplicate events.
  • Secure your secret. Store DODO_PAYMENTS_WEBHOOK_KEY in environment variables or a secrets manager, never in version control.

Webhook Payload Structure

Request Format

Headers

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

Request Body

string
required
Your Dodo Payments business identifier.
string
required
Event type that triggered this webhook (e.g., payment.succeeded, subscription.active).
string
required
ISO 8601 formatted timestamp of when the event occurred.
object
required
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

Send an Example Event

Test your webhook integration directly from the dashboard:
1

Navigate to Webhooks

Go to Developer → Webhooks and click on your endpoint.
2

Open Testing Tab

Click the Testing tab.
3

Send Example

Select an event type and click Send example. The sample payload is delivered to your endpoint URL exactly like a real event, signed the same way.
4

Check Your Endpoint

Confirm the event arrived, that your signature verification passed, and that you returned a 2xx status code.
Failed messages sent from the Testing tab are retried on the normal retry schedule, like any other webhook.

Implementation Example

Complete Express.js implementation with 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 has two commands for testing webhooks during local development.

Listen for Live Webhooks Locally

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

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 the subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, and entitlement grant families. It does not send subscription.past_due or subscription.unpaused. See Supported Webhook Events for the exact list.
Mock webhook payloads from dodo wh trigger are not signed. Use the unverified parse method (unsafeUnwrap in TypeScript, unsafe_unwrap in Python, UnsafeUnwrap in Go) 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. By default, webhooks have no rate limit applied and events are delivered as soon as they occur.
1

Open Advanced Tab

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

Configure Rate Limit

Expand the Endpoint throttling section.
3

Set Your Limit

Enter the maximum number of messages per second, then click Save. Deliveries beyond this rate are queued rather than dropped.

Custom Headers

Add custom HTTP headers to all webhook requests sent to your endpoint. Useful for authentication, routing, or adding metadata.
1

Add Headers

In the Custom headers section, enter a header name and value.
2

Add Multiple Headers

Click Add header for each additional header, then click Save.

Transformations

Transformations allow you to modify a webhook’s payload and optionally redirect it to a different URL. Use transformations 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

In the Transformation section, turn on Enable transformation.
2

Configure Transformation

Write your transformation rules in JavaScript in the code editor, then click Save. The code must return the webhook object from handler().
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.

Monitoring Webhook Logs

The Logs tab provides visibility into your webhook delivery status.
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 to re-drive that one message without leaving the page.

Activity Monitoring

Go to Developer → Webhooks and open the Activity tab to see 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 shows which endpoints need attention at a glance.

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.
  • 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:
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

The webhooks dashboard doesn’t offer email alerts for failing deliveries. To monitor deliveries, go to Developer → Webhooks and check the Logs and Activity tabs.

Deploy to Cloud Platforms

Platform-specific guides for deploying webhook handlers to popular cloud providers:

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

Create Webhook

Create and configure webhook endpoints programmatically

List Webhooks

Retrieve and manage your webhook endpoints
Last modified on September 26, 2026