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).

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:

{
  "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 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.

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.