This is the full catalog of webhook event types Kontorion emits. For setup, signature verification, retries, and dedup semantics see the Webhooks Guide.
Event names follow <noun>.<past_tense_verb> in snake_case. The noun side may be compound (reserve_outcome, usage_event); the verb describes the transition that just happened, not a future state. Subscribe to events by listing every type explicitly on the endpoint - wildcard subscriptions don't exist.
Customers
Event
When
customer.created
A new customer is created
customer.mode_changed
The customer's billing mode flipped between PREPAID and POSTPAID. Wallets inherit the change automatically
Subscriptions
Event
When
subscription.created
A new subscription is created
subscription.activated
A subscription transitions to ACTIVE (trial ended, first activation)
subscription.cancelled
A subscription is cancelled
subscription.paused
A subscription is paused
subscription.resumed
A paused subscription is resumed
subscription.dunning_entered
A subscription transitions into DUNNING after a payment fails
subscription.dunning_stage_changed
The dunning_stage advanced (e.g. WARNED → GRACED → SUSPENDED); the top-level status stays DUNNING
subscription.recovered
A previously failing subscription returns to ACTIVE after payment clears
subscription.payment_failed
A scheduled payment attempt failed against an active subscription
subscription.plan_changed
A subscription moved to a different plan version
subscription.quantity_changed
A subscription's quantity is adjusted mid-period
subscription.item_added
An add-on or item was attached to the subscription
subscription.item_removed
An add-on or item was removed from the subscription
subscription.refund_required
A change requires a refund (mid-cycle downgrade, item removal with prepaid balance)
Invoicing
Event
When
invoice.generated
A new invoice is created in draft
invoice.pending_approval
An invoice is queued behind an approval gate
invoice.finalized
An invoice is finalized - number assigned, totals locked, billable to customer
invoice.payment_recorded
A payment posted against an invoice (gateway success or manual record)
invoice.overdue
A finalized invoice passed its due_date without full payment - emitted by the dunning Phase-1 transition
invoice.voided
An invoice was voided
There is no invoice.paid event in the current taxonomy - react to invoice.payment_recorded and check payload.status == "paid", or to subscription.recovered for the dunning-recovery case.
Credit notes
Event
When
credit_note.created
A credit note is created in draft
credit_note.issued
A credit note is issued - number assigned, customer-visible
credit_note.applied
A credit note application posted against an invoice (or wallet)
credit_note.voided
A credit note was voided
Dunning
Event
When
dunning.step.email
A send_email step executed - payload carries email_event for downstream routing
dunning.step.grace
A grace step executed
dunning.step.suspend
A suspend step executed (typically alongside subscription.dunning_stage_changed with the new stage SUSPENDED)
dunning.step.cancel
A cancel step executed (typically alongside subscription.cancelled)
invoice.overdue is the precondition that gates the dunning runner - it's listed under Invoicing.
Wallets
Event
When
wallet.transferred
Funds were transferred between two wallets (same- or cross-currency)
wallet.hold_expired
A wallet hold timed out at its expires_at and released without capture
wallet.auto_topup_triggered
Auto top-up fired against a wallet (cash balance below low_balance_threshold)
wallet.payment_skipped
A wallet draw against an invoice was permanently skipped (no eligible wallet, currency mismatch, etc.)
Mode changes are emitted as customer.mode_changed, not wallet.mode_changed - mode lives on the customer and cascades to all their wallets.
Plans and scheduled changes
Event
When
plan.published
A new plan version was published
plan.subscribers_migrated
Subscribers were moved onto a newly published plan version (bulk migrate)
scheduled_change.created
A scheduled change is queued
scheduled_change.upcoming
A scheduled change entered its notification window
scheduled_change.reconfirmed
A stale scheduled change was reconfirmed back into pending
scheduled_change.released
A scheduled change was applied at its scheduled_at (or via manual release)
scheduled_change.cancelled
A scheduled change was cancelled before release
scheduled_change.rolled_back
A released scheduled change was rolled back within its rollback_window
Promotions
Lifecycle - promotion-level transitions:
Event
When
promotion.created
A new promotion was created
promotion.updated
An existing promotion was updated (within its phase rules)
