Webhook Event Guide

Dodo Payments provides real-time webhook notifications to keep you informed about critical events related to transactions, subscriptions, refunds, disputes, and license key management. Below is a detailed guide to these events, categorized for clarity, along with implementation tips and considerations.

Payment Events

Event Name	Event Type	Description
Payment Succeeded	`payment.succeeded`	Triggered when a payment is successfully processed.
Payment Failed	`payment.failed`	Occurs when a payment attempt fails due to errors, declined cards, or other issues.
Payment Processing	`payment.processing`	Indicates that a payment is currently being processed.
Payment Cancelled	`payment.cancelled`	Triggered when a payment is cancelled before completion.

Refund Events

Event Name	Event Type	Description
Refund Succeeded	`refund.succeeded`	Triggered when a refund is successfully processed.
Refund Failed	`refund.failed`	Occurs when a refund attempt fails due to processing errors or other issues.

Dispute Events

Event Name	Event Type	Description
Dispute Opened	`dispute.opened`	Triggered when a customer initiates a dispute.
Dispute Expired	`dispute.expired`	Indicates that a dispute expired without resolution.
Dispute Accepted	`dispute.accepted`	Triggered when a merchant accepts the dispute.
Dispute Cancelled	`dispute.cancelled`	Occurs when a dispute is cancelled by the customer or system.
Dispute Challenged	`dispute.challenged`	Triggered when a merchant challenges a dispute.
Dispute Won	`dispute.won`	Indicates that the merchant has successfully won a dispute.
Dispute Lost	`dispute.lost`	Occurs when the merchant loses a dispute.

Subscription Events

Event Name	Event Type	Description
Subscription Active	`subscription.active`	Indicates that a subscription is now active and recurring charges are scheduled.
Subscription Updated	`subscription.updated`	Triggered when any subscription field is updated (real-time sync without polling).
Subscription On Hold	`subscription.on_hold`	Triggered when a subscription is temporarily put on hold due to failed renewal.
Subscription Renewed	`subscription.renewed`	Occurs when a subscription is successfully renewed.
Subscription Plan Changed	`subscription.plan_changed`	Triggered when a subscription is upgraded, downgraded, or modified with different addons.
Subscription Payment Method Updated	`subscription.update_payment_method`	Sent when a subscription’s payment method is updated. Carries the Subscription payload.
Subscription Cancelled	`subscription.cancelled`	Triggered when a subscription is cancelled by the merchant or customer.
Subscription Failed	`subscription.failed`	Indicates a failed subscription. This means that we were unable to create a mandate.
Subscription Expired	`subscription.expired`	Triggered when a subscription reaches the end of its term and expires.

License Key Events

Event Name	Event Type	Description
License Key Created	`license_key.created`	Triggered when a new license key is created for a product.

Entitlement Grant Events

Event Name	Event Type	Description
Grant Created	`entitlement_grant.created`	A new entitlement grant is created for a customer. License-key grants arrive `delivered`; OAuth-based grants (Discord, GitHub, Notion) arrive `pending`.
Grant Delivered	`entitlement_grant.delivered`	Grant fulfilment completes — license key issued, file links resolved, or platform access granted.
Grant Failed	`entitlement_grant.failed`	Grant fulfilment failed; inspect `error_code` and `error_message`.
Grant Revoked	`entitlement_grant.revoked`	Access is withdrawn; inspect `revocation_reason` (subscription state, refund, plan change, or manual).

For detailed payload schemas, sample events, and the full revocation_reason reference, see Entitlement Grant Webhooks.

Credit Events

Event Name	Event Type	Description
Credit Added	`credit.added`	Triggered when credits are granted to a customer (subscription, one-time, add-on, or API).
Credit Deducted	`credit.deducted`	Occurs when credits are consumed through usage or manual debit.
Credit Expired	`credit.expired`	Triggered when unused credits expire after the configured expiry period.
Credit Rolled Over	`credit.rolled_over`	Occurs when unused credits are carried forward to a new grant at cycle end.
Rollover Forfeited	`credit.rollover_forfeited`	Triggered when credits are forfeited because the max rollover count was reached.
Overage Charged	`credit.overage_charged`	Occurs when overage charges are applied for usage beyond zero balance.
Overage Reset	`credit.overage_reset`	Triggered when accumulated overage charges are reset (for example, at the start of a new billing cycle).
Manual Adjustment	`credit.manual_adjustment`	Triggered when a manual credit or debit adjustment is made.
Balance Low	`credit.balance_low`	Triggered when credit balance drops below the configured threshold.

Recovery Events

Event Name	Event Type	Description
Abandoned Checkout Detected	`abandoned_checkout.detected`	Triggered when an incomplete or failed checkout is detected after 60 minutes.
Abandoned Checkout Recovered	`abandoned_checkout.recovered`	Occurs when a customer completes payment through a recovery link.

For detailed payload schemas, field descriptions, and handler examples, see Recovery Webhooks.

Dunning Events

Event Name	Event Type	Description
Dunning Started	`dunning.started`	Triggered when a dunning attempt begins for a subscription that went on hold or was cancelled.
Dunning Recovered	`dunning.recovered`	Occurs when a customer updates their payment method and the resulting charge succeeds.

For detailed payload schemas, field descriptions, and handler examples, see Recovery Webhooks.

Payout Events

These events track the movement of your funds from Dodo Payments to your bank account, mirroring the payout statuses shown in the dashboard. The payload is a payout object with the same shape as an entry from GET /payouts.

Event Name	Event Type	Description
Payout Created	`payout.created`	Triggered when a payout is created, either by the automatic payout cycle or off-cycle.
Payout In Progress	`payout.in_progress`	Occurs when the payout due date arrives and the payout starts processing.
Payout On Hold	`payout.on_hold`	Triggered when a payout is paused or placed under review.
Payout Successful	`payout.success`	Occurs when the payout to your bank account is processed successfully.
Payout Failed	`payout.failed`	Triggered when a payout fails. The funds and fees are credited back to your wallet.

Do not assume payout events are terminal or strictly ordered. payout.failed can legitimately arrive after payout.success when a bank returns the transfer, and payout.success can arrive after payout.failed when a failed payout is later recovered. Always treat the status on the payload as the current state.

payout.created was previously emitted as payout.not_initiated. If you have an existing endpoint filtering on payout.not_initiated, update the filter to payout.created so it keeps matching.

For detailed payload schemas, field descriptions, and handler examples, see Payout Webhooks. These webhook events are designed to provide merchants with critical updates to manage their operations effectively. Implement robust handlers for each relevant event in your webhook integration to ensure smooth and reliable functionality.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Payment Events

Refund Events

Dispute Events

Subscription Events

License Key Events

Entitlement Grant Events

Credit Events

Recovery Events

Dunning Events

Payout Events

​Payment Events

​Refund Events

​Dispute Events

​Subscription Events

​License Key Events

​Entitlement Grant Events

​Credit Events

​Recovery Events

​Dunning Events

​Payout Events

Payment Events

Refund Events

Dispute Events

Subscription Events

License Key Events

Entitlement Grant Events

Credit Events

Recovery Events

Dunning Events

Payout Events