Event reference
Invoice lifecycle webhooks carry the same payload shape ({ event_id, event_type, created_at, livemode, data: { invoice } }).
| Event type | Fired when | May fire more than once? |
|---|---|---|
invoice.created | New invoice via POST /v1/invoices | no |
invoice.payment_seen | Payment observed, typically in mempool before confirmation | Do not rely on a once-only guarantee |
invoice.paid | Cumulative confirmed amount within tolerance, before expiry | no |
invoice.late_paid | Cumulative confirmed amount within tolerance, after expiry in a supported late/recovery flow | no |
invoice.expired | pending invoice's expires_at elapsed with no payment. A detected payment is monitored instead of expiring solely by the clock; stale unconfirmed payments can require review. | no |
invoice.underpaid | Transition to a short-payment state. A top-up that leaves status unchanged may not create a new event. | yes |
invoice.overpaid | Cumulative confirmed amount exceeds amount_sats + tolerance | no |
invoice.payment_reverted | A reorg orphaned the block containing the payment. Reconcile your order and follow your refund or fulfillment policy. Already completed fulfillment may not be reversible. | very rare |
invoice.requires_review | Routing produced "no-match" or cross-check disagreed | rare |
invoice.cancelled | Vendor or admin cancelled | no |
invoice.grace_ending | Opt-in: fires once near the end of the late-payment grace window (endpoint must enable graceEndingEnabled) | no |
invoice.reopened | Invoice reopened after a prior terminal-ish state (lifecycle edge case) | rare |
The table describes typical lifecycle emissions, not an exactly-once delivery guarantee. Reopened invoices and additional payments can produce further events. Always deduplicate by
event_id, never byinvoice.id+event_type. A new status transition can create a new event ID; an unchanged short-payment state may not. Dispatcher retries reuse the sameevent_id.