> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks overview
> How Flexprice webhooks deliver invoice, payment, subscription, wallet, and usage events to your systems
Webhooks push a notification to your server when something changes in Flexprice: an invoice is finalized, a payment succeeds or fails, a subscription changes plan, a wallet balance drops below a threshold, or a usage event is rejected. They replace polling for anything that has to happen promptly after a billing event.
**Benefits:**
* **Push, not poll**: your system learns about a change within seconds instead of on the next sync
* **Signed and retried**: every delivery on Flexprice Cloud is signed with HMAC-SHA256 and retried for days on failure
* **Typed payloads**: each event's JSON is documented in the API reference and modelled in every SDK
## How webhook delivery works
Add an HTTPS URL in the dashboard under **Developers > Webhooks** and pick the events it should receive. Each endpoint gets its own signing secret. See [Set up an endpoint](/developers/webhooks/set-up-an-endpoint).
The body is JSON with an `event_type` and the object that changed:
```json theme={null}
{
"event_type": "invoice.update.finalized",
"invoice": { "id": "inv_01J...", "invoice_status": "FINALIZED", "amount_due": "149.00" }
}
```
Check the signature on the raw body, return `2xx` within 5 seconds, and do the work on a queue. See [Signature verification](/developers/webhooks/signature-verification).
A non-`2xx` response or a timeout is retried on a backoff schedule, so handlers must tolerate duplicates and reordering. See [Retries and ordering](/developers/webhooks/retries-and-ordering).
## Which events Flexprice sends
Sixty event types cover customers, subscriptions, invoices, payments, refunds, credit notes, wallets, features, entitlements, checkout sessions, and usage ingestion. The [event catalog](/developers/webhooks/event-catalog) lists every one with a link to its payload schema. The ones most integrations start with:
| Event | Fires when |
| - | - |
| `invoice.update.finalized` | An invoice is finalized and ready for payment |
| `invoice.update.payment` | A payment is recorded against an invoice |
| `payment.success`, `payment.failed` | A payment attempt completes |
| `subscription.created`, `subscription.cancelled` | A subscription starts or ends |
| `subscription.plan_changed` | A customer moves between plans |
| `wallet.credit_balance.dropped` | A wallet crosses its low-balance threshold |
| `event.rejected` | A usage event was accepted but could not be metered |
## Webhook delivery on Cloud and self-hosted
| | Flexprice Cloud | Self-hosted, default | Self-hosted with Svix enabled |
| - | - | - | - |
| Delivered by | [Svix](https://docs.svix.com/) | Native HTTP client | Svix |
| Signature | HMAC-SHA256 in `svix-signature` | None; use a static header from tenant config | HMAC-SHA256 |
| Retries | 8 attempts over about a day | 3 attempts within 2 minutes | 8 attempts over about a day |
| Delivery logs and replay | Dashboard | Server logs | Dashboard |
Flexprice Cloud always uses Svix. A self-hosted instance uses native delivery unless Svix is turned on in [configuration](/docs/getting-started/configuration#webhook-configuration).
## Webhook handler best practices
1. **Verify every signature** before reading the body.
2. **Respond fast and process later.** Anything over 5 seconds is a failure.
3. **Dedupe on `svix-id`.** Delivery is at-least-once.
4. **Treat payloads as snapshots.** Read the status from the body and compare `updated_at` rather than assuming order.
5. **Return `200` for events you do not handle** so they are not retried.
6. **Register separate endpoints per environment** with separate secrets.
7. **Subscribe to `event.rejected`** so dropped usage is never silent.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.