# 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 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`.

---