Webhook Events Guide

Dodo Payments emits webhook events at each stage of a payment, subscription, dispute, payout, credit, or license key lifecycle. This page lists every event by resource. For detailed payload schemas and handler examples, see the resource-specific pages linked below.

Payment Events

Event	Fires when
`payment.succeeded`	A payment is successfully processed.
`payment.failed`	A payment attempt fails due to declined cards, insufficient funds, or other errors.
`payment.processing`	A payment is being processed.
`payment.cancelled`	A payment is cancelled before completion.

For the full payload schema, see Payment Webhooks.

Refund Events

Event	Fires when
`refund.succeeded`	A refund is successfully processed.
`refund.failed`	A refund attempt fails due to processing errors or other issues.

For the full payload schema, see Refund Webhooks.

Dispute Events

Event	Fires when
`dispute.opened`	A cardholder opens a dispute on a payment.
`dispute.challenged`	Evidence has been submitted to contest the dispute.
`dispute.accepted`	The dispute was accepted without being contested.
`dispute.cancelled`	The dispute was withdrawn or cancelled.
`dispute.expired`	The response window passed without resolution.
`dispute.won`	The dispute was resolved in your favor.
`dispute.lost`	The dispute was resolved in the cardholder’s favor.

For detailed payload schemas and handler examples, see Dispute Webhooks.

Subscription Events

Event	Fires when
`subscription.active`	A subscription is successfully activated and recurring charges are scheduled.
`subscription.updated`	Any subscription field changes (real-time sync without polling).
`subscription.past_due`	A renewal fails and the grace period opens; the customer keeps access until the deadline.
`subscription.on_hold`	A subscription is temporarily put on hold due to failed renewal.
`subscription.paused`	A subscription is paused.
`subscription.unpaused`	A paused subscription is resumed.
`subscription.renewed`	A subscription is successfully renewed for the next billing period.
`subscription.plan_changed`	A subscription is upgraded, downgraded, or modified with different add-ons.
`subscription.update_payment_method`	A subscription’s payment method is updated.
`subscription.cancelled`	A subscription is cancelled by the merchant or customer.
`subscription.failed`	Subscription creation fails during mandate creation.
`subscription.expired`	A subscription reaches the end of its term and expires.

For detailed payload schemas and handler examples, see Subscription Webhooks.

License Key Events

Event	Fires when
`license_key.created`	A new license key is created for a product.

For the full payload schema, see License Key Webhooks.

Entitlement Grant Events

Event	Fires when
`entitlement_grant.created`	A new entitlement grant is created for a customer. Auto-fulfilled license-key grants and feature-flag grants arrive with `status: "Delivered"` and fire no separate `delivered` event. Other grants, including manually-fulfilled license keys, arrive `Pending`. See Entitlement Grant.
`entitlement_grant.delivered`	Grant fulfillment completes — license key issued, file links resolved, or platform access granted.
`entitlement_grant.failed`	Grant fulfillment fails. Check `error_code` and `error_message` in the payload.
`entitlement_grant.revoked`	Access is withdrawn. Check `revocation_reason` in the payload.

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

Credit Events

Event	Fires when
`credit.added`	Credits are granted to a customer (via subscription, one-time purchase, add-on, or API).
`credit.deducted`	Credits are consumed through usage or manual debit.
`credit.expired`	Unused credits expire after the configured expiry period.
`credit.rolled_over`	Unused credits are carried forward to a new grant at cycle end.
`credit.rollover_forfeited`	Credits are forfeited because the max rollover count was reached.
`credit.overage_charged`	Overage charges are applied for usage beyond zero balance.
`credit.overage_reset`	Accumulated overage charges are reset (for example, at the start of a new billing cycle).
`credit.manual_adjustment`	A manual credit or debit adjustment is made.
`credit.balance_low`	Credit balance drops below the configured threshold.

For detailed payload schemas and handler examples, see Credit-Based Billing Webhooks.

Recovery Events

Event	Fires when
`abandoned_checkout.detected`	An incomplete or failed checkout is detected after 60 minutes.
`abandoned_checkout.recovered`	A customer completes payment through a recovery link.

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

Dunning Events

Event	Fires when
`dunning.started`	A dunning attempt begins for a subscription that went past due or on hold, or was cancelled.
`dunning.recovered`	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

Payout events track your funds moving from Dodo Payments to your bank account. They mirror the payout statuses shown in the dashboard. The payload is a payout object with the same shape as an entry from GET /payouts.

Event	Fires when
`payout.created`	A payout is created, either by the automatic payout cycle or off-cycle.
`payout.in_progress`	The payout due date arrives and processing starts.
`payout.on_hold`	A payout is paused or placed under review.
`payout.success`	The payout to your bank account settles.
`payout.failed`	A payout fails. The funds and fees are credited back to your wallet.

Payout events are neither terminal nor strictly ordered. payout.failed can 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. The payload’s status always matches the event type, so use each event’s top-level timestamp to find the latest state.

payout.created was previously emitted as payout.not_initiated. If an existing endpoint filters 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.

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