Dodo Payments webhook

POST

/webhooks/dodo

• API base path

Receives subscription lifecycle events from Dodo Payments. Verified using HMAC-SHA256 signature following the Standard Webhooks specification.

This endpoint is called by Dodo Payments, not by API consumers.

Parameters

Header Parameters

webhook-id

required

string

Unique webhook delivery ID

webhook-timestamp

required

string

Unix timestamp of the webhook delivery

webhook-signature

required

string

HMAC-SHA256 signature in format: v1,

Request Body ^required

object

event

required

Subscription lifecycle event type

string

Allowed values: subscription.active subscription.cancelled subscription.on_hold subscription.plan_changed subscription.renewed

Example

subscription.active

timestamp

Event timestamp

string format: date-time

Example

2026-02-10T12:00:00.000Z

data

required

object

subscription_id

Dodo Payments subscription ID

string

Example

sub_abc123

customer_id

Dodo Payments customer ID

string

Example

cust_xyz789

product_id

Product ID mapped to a plan (prod_starter, prod_pro, prod_scale)

string

Example

prod_pro

status

Subscription status

string

Example

active

Responses

200

Webhook processed

object

received

required

boolean

Example

true

401

Invalid webhook signature

object

error

required

object

code

required

Machine-readable error code

string

Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR

Example

VALIDATION_ERROR

message

required

Human-readable error message

string

Example

Invalid request body

details

Additional error details (e.g., validation issues)

object

key

additional properties

any

Example

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid webhook signature"
  }
}