​

Introduction

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

​

Getting Started

2. Click on Add Webhook to create a new webhook endpoint.
3. Navigate to the DodoPayments Dashboard and go to Settings > API Keys.
4. Enter the URL where you want to receive webhook events.
5. Obtain your webhook Secret Key from the settings page. You’ll use this to verify the authenticity of received webhooks.

​

Webhook Delivery

​

Timeouts

• Webhooks have a 10-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 10 retries for each failed webhook delivery.
• The initial retry delay is 6 seconds, and the maximum delay between retries is capped at 6 hours.

​

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.

​

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 API Reference.

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.

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.