Webhooks overview

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.

Flexprice sends a POST

The body is JSON with an event_type and the object that changed:

{
  "event_type": "invoice.update.finalized",
  "invoice": { "id": "inv_01J...", "invoice_status": "FINALIZED", "amount_due": "149.00" }
}

Your handler verifies, acknowledges, and processes

Check the signature on the raw body, return 2xx within 5 seconds, and do the work on a queue. See Signature verification.

Failures are retried

A non-2xx response or a timeout is retried on a backoff schedule, so handlers must tolerate duplicates and reordering. See 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 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	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.

Webhook handler best practices

Verify every signature before reading the body.
Respond fast and process later. Anything over 5 seconds is a failure.
Dedupe on svix-id. Delivery is at-least-once.
Treat payloads as snapshots. Read the status from the body and compare updated_at rather than assuming order.
Return 200 for events you do not handle so they are not retried.
Register separate endpoints per environment with separate secrets.
Subscribe to event.rejected so dropped usage is never silent.