Agent skill

Flexprice Webhooks Skill

Receive and verify Flexprice webhooks (open-source usage-based billing, delivered via Svix on Flexprice Cloud). Use when setting up Flexprice webhook handlers, debugging svix-signature verification, or handling events like invoice.update.finalized, payment.success, subscription.cancelled, and wallet.credit_balance.dropped.

Install this skill

npx skills add hookdeck/webhook-skills --skill flexprice-webhooks


Flexprice Cloud delivers webhooks through Svix, which implements Standard Webhooks. Every delivery is an HTTP POST with a JSON body and three signature headers: svix-id, svix-timestamp, and svix-signature. The event name is the top-level event_type field, and the changed object sits under a resource-named key (invoice, payment, subscription, wallet, customer, ...), not under data.

Only Flexprice Cloud signs webhooks

Hookdeck's configuration alert for this source reads: "Only Flexprice Cloud signs webhooks. Self-hosted Flexprice sends unsigned deliveries, which fail verification."

Flexprice Cloud always delivers through Svix and signs every delivery. A self-hosted instance signs only when Svix is enabled in its configuration. Its default native delivery sends the JSON body with no signature (Flexprice's docs suggest a static secret header from the tenant's webhook settings instead), so nothing here can verify it. See references/setup.md.

When to Use This Skill

  • How do I receive Flexprice webhooks?
  • How do I verify Flexprice webhook signatures (svix-signature)?
  • How do I handle invoice.update.finalized or payment.success events?
  • How do I react to wallet.credit_balance.dropped or subscription.spend.threshold_reached?
  • Why is my Flexprice webhook signature verification failing, or rejecting Hookdeck retries?

Verification (core)

Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use the official svix library, which compares in constant time. Read the svix-* headers, and when svix-id is absent fall back to the webhook-* headers (webhook-id, webhook-timestamp, webhook-signature).

import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.FLEXPRICE_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["FLEXPRICE_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

The secret is shown on the endpoint's page in the Flexprice dashboard and starts with whsec_. Each endpoint has its own, and sandbox and production endpoints are separate. Keep the full whsec_... value in FLEXPRICE_WEBHOOK_SECRET. Handlers fail closed: with the variable unset they return 500 instead of accepting anything.

Hookdeck retries and replays hit the 5-minute window

The svix and standardwebhooks libraries always enforce a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on svix-id instead of relying on the timestamp.

Common Event Types

60 events are documented. The name is event_type in the JSON body. The examples handle these:

EventTriggered When
customer.createdA customer is created (also customer.updated, customer.deleted)
subscription.createdA subscription is created
subscription.activatedA draft subscription is activated
subscription.updatedA subscription changes (quantity, billing anchor, metadata)
subscription.plan_changedA subscription moves to another plan in place
subscription.cancelledA subscription is cancelled
invoice.update.finalizedAn invoice is finalized and locked for payment
invoice.update.paymentAn invoice's payment status changes
invoice.update.voidedAn invoice is voided
invoice.payment.overdueAn invoice is past its due date
payment.successA payment succeeds
payment.failedA payment fails
wallet.credit_balance.droppedA wallet's credit balance drops below an alert threshold
checkout.session.completedPayment confirmed; subscription active, invoice finalized
event.rejectedA usage event matched no meter and was dropped

See references/overview.md for the full catalog and payload shape.

Environment Variables

# Signing secret of the webhook endpoint (Svix format, starts with whsec_)
FLEXPRICE_WEBHOOK_SECRET=whsec_xxxxx

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 flexprice --path /webhooks/flexprice

Register the tunnel URL as an endpoint under Developers > Webhooks in the Flexprice dashboard, then trigger an event (for example, create a customer) to see it arrive.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →