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

> Learn about webhook events in Flexprice

Webhooks let you receive real-time notifications about events in your Flexprice account, such as invoice creation, payment status updates, subscription changes, and more.
There are **two ways** webhooks can be delivered:

* **Native Flexprice Webhooks**: Simple, direct POST to your endpoint.
* **Svix Webhooks**: Advanced, robust delivery with retries, history, signatures, and more (powered by [Svix](https://docs.svix.com/)).

**Flexprice Cloud uses Svix for webhook delivery. For self hosting, if you haven't explicitly enabled Svix, you're using native webhooks by default.**

## Webhook Event Types

You can receive webhook notifications for a range of events:

### Invoice Events

* `invoice.create.drafted` - Fired when a new invoice is created in draft state
* `invoice.update.finalized` - Fired when an invoice is finalized and ready for payment
* `invoice.update.payment` - Fired when a payment is recorded on an invoice
* `invoice.update.voided` - Fired when an invoice is voided
* `invoice.payment.overdue` - Fired when an invoice payment is overdue

### Subscription Events

* `subscription.created` - Fired when a new subscription is created
* `subscription.updated` - Fired when a subscription is updated
* `subscription.paused` - Fired when a subscription is paused
* `subscription.cancelled` - Fired when a subscription is cancelled
* `subscription.resumed` - Fired when a paused subscription is resumed

### Feature Events

* `feature.created` - Fired when a new feature is created
* `feature.updated` - Fired when feature details are updated
* `feature.deleted` - Fired when a feature is deleted

### Entitlement Events

* `entitlement.created` - Fired when a new entitlement is created
* `entitlement.updated` - Fired when entitlement details are updated
* `entitlement.deleted` - Fired when an entitlement is deleted

### Wallet Events

* `wallet.created` - Fired when a new wallet is created
* `wallet.updated` - Fired when wallet details are updated
* `wallet.terminated` - Fired when a wallet is terminated
* `wallet.transaction.created` - Fired when a new wallet transaction is created

### Payment Events

* `payment.created` - Fired when a new payment is created
* `payment.updated` - Fired when payment details are updated
* `payment.failed` - Fired when a payment attempt fails
* `payment.success` - Fired when a payment is successful
* `payment.pending` - Fired when a payment is awaiting processing

### Customer Events

* `customer.created` - Fired when a new customer is created
* `customer.updated` - Fired when customer information is updated
* `customer.deleted` - Fired when a customer is deleted

*(More event types may be added in the future.)*

## Webhook Payload Format

Every webhook payload follows this structure:

```json theme={null}
{
  "subscription": "<subscription object>"
}
```

* All event types use this base schema
* The payload field contains event-specific data

## How Webhook Delivery Works

### Native Webhook System

* **Default mode.**
* When a subscribed event occurs, Flexprice makes a simple HTTP POST to your provided webhook URL.
* A JSON payload with event data is sent.
* If your endpoint responds with a `2xx` status, the event is marked as delivered.
* If your endpoint fails (non-2xx, timeout, etc.), Flexprice attempts retries with the following configuration:
  * Maximum retries: 3 (default)
  * Initial interval: 1 second
  * Maximum interval: 10 seconds
  * Multiplier: 2.0
  * Maximum elapsed time: 2 minutes

**Summary:**
Fast, direct, and simple. Good for lightweight use-cases or internal integrations.

### Svix Webhook System

* **Advanced mode** (opt-in; see [Svix docs](https://docs.svix.com/) for more on their delivery system).
* When enabled, Flexprice hands off event delivery to Svix.
* Svix provides:
  * **Robust retries:** Automatic, exponential backoff, no event lost due to transient issues
  * **Delivery guarantees:** At-least-once delivery, dead-letter queues for persistent failures
  * **Message history and logs:** Track every delivery, status, and error online
  * **Signature verification:** Every request is signed with HMAC-SHA256 for security
  * **Versioning & secret management:** Change secrets or endpoint URLs safely without missed events

The retry schedule for failed deliveries is:

* 5 minutes after the first failure
* 30 minutes after the second failure
* 2 hours after the third failure
* 5 hours after the fourth failure
* 10 hours after the fifth failure

**Summary:**
Svix is the recommended choice for production, customer-facing, or high-uptime integrations. If you want reliability, observability, and security, use Svix.

## Setting Up Webhooks

To enable webhooks on flexprice:

1. Go to the **Webhooks** section in your Flexprice dashboard
2. Click the **Add Endpoint** button
3. Enter your endpoint URL (e.g., `https://play.svix.com/in/e_...`)
4. The endpoint will be created with a 0.0% error rate initially
5. You can monitor message delivery, view logs, and track activity in the dashboard

Your configured webhook endpoint will be displayed in the **Endpoints** tab, where you can:

* View the error rate for message delivery
* Access message logs with detailed delivery information
* See historical delivery attempts and statistics
* Monitor webhook activity in real-time

The **Event Catalog** tab shows all available event types you can subscribe to, with detailed descriptions of when each event is fired.

The **Logs** tab provides a comprehensive view of message delivery attempts, including:

* Event type
* Message ID
* Timestamp
* Delivery status
* Detailed error information if delivery fails

The **Activity** tab shows historical delivery metrics and attempts over time.

## Security & Verification

* Every payload is signed using HMAC-SHA256 (default) or Ed25519
* Verify signatures using:
  * Svix's official SDKs
  * Manual verification using `svix-signature`, `svix-id`, and `svix-timestamp` headers
* Automatic timestamp validation prevents replay attacks
* Optional IP address validation

For detailed signature verification instructions, see the [Svix signature docs](https://docs.svix.com/receiving/verifying-payloads).

## Best Practices

1. **Use Svix for Production**: If you're building a production system, use Svix for its reliability and security features.
2. **Always Verify Signatures**: Whether using native or Svix webhooks, always verify the authenticity of incoming webhooks.
3. **Process Asynchronously**: Handle webhook processing in the background to avoid timeouts.
4. **Be Idempotent**: Design your handlers to safely process duplicate events.
5. **Use HTTPS**: Always use HTTPS endpoints for webhook delivery.
6. **Monitor Deliveries**: Regularly check webhook logs for failed deliveries.
7. **Quick Response**: Your endpoint should respond within 5 seconds to avoid timeouts.