
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
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
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: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.Configuring Subscribed Events
Configure which events each webhook endpoint receives.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
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.Save Configuration
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
Webhook Delivery
Timeouts
Webhooks have a 30-second timeout for both connection and read operations. Process webhooks asynchronously by returning a200 status code immediately, then handle the event in the background.
Automatic Retries
Failed deliveries are retried with exponential backoff, up to 8 attempts total:Idempotency
Each webhook includes a uniquewebhook-id header. Store this ID to detect and skip duplicate events, since retries may deliver the same event multiple times.
Event Ordering
Events may arrive out of order due to retries or network conditions. Each webhook includes atimestamp 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 awebhook-signature header: an HMAC SHA256 signature of the payload and timestamp, signed with your secret key.
SDK Verification (Recommended)
All official SDKs include built-in helpers. SetDODO_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.
unwrap / unsafeUnwrap in TypeScript, unwrap / unsafe_unwrap in Python, and Unwrap / UnsafeUnwrap in Go.
Manual Verification (Alternative)
If you’re not using an SDK, verify the signature yourself:- 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. - Take your webhook secret. If it starts with
whsec_, remove that prefix, then base64-decode the rest to get the signing key. - Compute the HMAC-SHA256 of the signed content with the signing key, and base64-encode the result.
- The
webhook-signatureheader holds one or more space-separated signatures, each in the formv1,<base64-signature>. The request is valid if anyv1signature matches yours. Compare with a constant-time function. - Reject the request if
webhook-timestampis too far from the current time, to prevent replay attacks. The Standard Webhooks libraries allow 5 minutes.
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 thewebhook-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.
Responding to Webhooks
Your webhook handler must return a2xx 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
200status code right away, then process the event asynchronously. - Implement idempotency. Use the
webhook-idheader to detect and skip duplicate events. - Secure your secret. Store
DODO_PAYMENTS_WEBHOOK_KEYin environment variables or a secrets manager, never in version control.
Webhook Payload Structure
Request Format
Headers
Request Body
payment.succeeded, subscription.active).Example Payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed and recover declined paymentsTesting Webhooks
Send an Example Event
Test your webhook integration directly from the dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx status code.Implementation Example
Complete Express.js implementation with webhook verification and handling: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:http://localhost:3000/webhook), preserving all headers for signature verification testing.
dodo login and select Test Mode first.Trigger Mock Webhook Events
Send mock webhook payloads to any endpoint without creating real transactions:subscription.past_due or subscription.unpaused. See Supported Webhook Events for the exact list.
CLI Webhook Testing Docs
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.Open Advanced Tab
Configure Rate Limit
Set Your Limit
Custom Headers
Add custom HTTP headers to all webhook requests sent to your endpoint. Useful for authentication, routing, or adding metadata.Add Headers
Add Multiple Headers
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
Enable Transformations
Configure Transformation
handler().Test Transformation
Monitoring Webhook Logs
The Logs tab provides visibility into your webhook delivery status.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- The complete webhook payload
- Every delivery attempt with response code and duration
- Timestamp of each attempt
- Any error messages from your endpoint
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.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:Open More Actions
Set the Range
Start the Run