Webhook Payloads
Credit-Based Billing Webhooks
The payload sent to your webhook endpoint when credit-based billing events occur — virtual credits granted, consumed, expired, rolled over, or balance alerts.
Credit-Based Billing Webhook Events
The following webhook events are available for tracking credit-based billing lifecycle changes. These events apply to virtual credit entitlements (API calls, tokens, compute hours), not to Customer Wallets (monetary balances).Ledger Events
All ledger events (credit.added through credit.manual_adjustment) share the same CreditLedgerEntryResponse payload documented in the schema below.
The payload includes a metadata field resolved from the credit grant’s source — the subscription or payment created at checkout. This lets you key wallet credits off your own checkout metadata (for example, an orgId) rather than the Dodo-issued customer_id: subscription-sourced grants surface the subscription’s metadata and payment-sourced grants surface the payment’s metadata. The field is empty when the grant has no resolvable source (for example, credits granted directly via the API).
Balance Low Event (credit.balance_low)
Thecredit.balance_low event uses a different payload (CreditBalanceLowPayload) focused on threshold alerting:
Using credit.balance_low for Proactive Alerts
Use the credit.balance_low webhook to notify customers before they run out of credits:
Get Customer Balance
Check a customer’s current balance via API.
Create Ledger Entry
Manually credit or debit a customer’s balance.
Webhook Payload Schema
Response for a ledger entry
Last modified on October 21, 2026