SatLane
Skip to documentation
Browse documentation

Event reference

Invoice lifecycle webhooks carry the same payload shape ({ event_id, event_type, created_at, livemode, data: { invoice } }).

Event typeFired whenMay fire more than once?
invoice.createdNew invoice via POST /v1/invoicesno
invoice.payment_seenPayment observed, typically in mempool before confirmationDo not rely on a once-only guarantee
invoice.paidCumulative confirmed amount within tolerance, before expiryno
invoice.late_paidCumulative confirmed amount within tolerance, after expiry in a supported late/recovery flowno
invoice.expiredpending 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.underpaidTransition to a short-payment state. A top-up that leaves status unchanged may not create a new event.yes
invoice.overpaidCumulative confirmed amount exceeds amount_sats + toleranceno
invoice.payment_revertedA 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_reviewRouting produced "no-match" or cross-check disagreedrare
invoice.cancelledVendor or admin cancelledno
invoice.grace_endingOpt-in: fires once near the end of the late-payment grace window (endpoint must enable graceEndingEnabled)no
invoice.reopenedInvoice 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 by invoice.id + event_type. A new status transition can create a new event ID; an unchanged short-payment state may not. Dispatcher retries reuse the same event_id.