> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events Guide

> Reference for all webhook events emitted by Dodo Payments, organized by resource. Each event fires at a specific point in a payment, subscription, dispute, or payout lifecycle.

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](/developer-resources/webhooks/intents/payment).

## 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](/developer-resources/webhooks/intents/refund).

## 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](/developer-resources/webhooks/intents/dispute).

## 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](/developer-resources/webhooks/intents/subscription).

## 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](/developer-resources/webhooks/intents/license-key).

## 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](/developer-resources/webhooks/intents/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](/developer-resources/webhooks/intents/entitlement-grant).

## 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](/developer-resources/webhooks/intents/credit).

## 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](/developer-resources/webhooks/intents/recovery).

## 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](/developer-resources/webhooks/intents/recovery).

## Payout Events

Payout events track your funds moving from Dodo Payments to your bank account. They mirror the [payout statuses](/features/payouts/payout-structure#payout-status) 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. |

<Warning>
  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.
</Warning>

<Note>
  `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.
</Note>

For detailed payload schemas, field descriptions, and handler examples, see [Payout Webhooks](/developer-resources/webhooks/intents/payout).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.