Webhooks

Receive real-time HTTP notifications when events occur in your store. Webhooks allow you to integrate FluxStore with external services such as Discord bots, CRMs, analytics platforms, and custom applications.

Overview

When an event occurs in your store (e.g. a payment is completed), FluxStore sends an HTTP POST request to your configured webhook URL with a JSON payload describing the event. Your endpoint should respond with a 2xx status code to acknowledge receipt.

Webhooks are a Pro plan feature.

Setup

1. Navigate to Dashboard > Webhooks
2. Enter your webhook URL
3. Toggle the events you want to receive
4. Optionally use the Package Filter to scope webhooks to a specific set of packages (see below)
5. Save your configuration

A signing secret is automatically generated when you create your webhook endpoint. Use this secret to verify that incoming requests are genuinely from FluxStore.

Package filter

The Package Filter controls which packages trigger webhooks for events that are scoped to a package (all order.*, subscription.* events). Events without package context (refunds, chargebacks) ignore the filter.

Pick one of two modes:

• Deny-list (default): webhooks fire for every package except the ones you list. Use this when you have a few packages you don’t want to notify your plugin about: donations, in-game currency, cosmetic-only rewards, etc.
• Allow-list: webhooks fire only for the packages you list. Use this when your plugin handles a narrow subset and you don’t want noise from the rest of the store.

For a mixed-cart order, the rule applies to the order as a whole:

• Deny-list: the order is skipped only when every item is on the list. An order with one listed package and one unlisted package still fires; your plugin sees the full items array and should ignore the listed IDs.
• Allow-list: the order fires when any item matches the list. Again the payload contains the full items array; filter on your end.

Event types

Payment events

Dispute events

Subscription events

Utility events

Webhook payload

All webhooks are sent as POST requests with a Content-Type: application/json header. Every payload follows the same envelope structure:

{
  "event": "order.completed",
  "timestamp": "2026-03-09T12:00:00Z",
  "store_id": "a1b2c3d4-...",
  "data": {
    // Event-specific data
  }
}

Request headers

Every webhook request includes the following headers:

Delivery & retries

• Webhooks are delivered within seconds of the event occurring
• If your endpoint returns a non-2xx status code or times out, FluxStore will retry up to 3 times
• Retries are attempted every 10 seconds
• After 3 failed attempts, the delivery is marked as failed
• All delivery attempts are logged in the Delivery Logs section of the Webhooks dashboard
• Request timeout is 15 seconds

Best practices

1. Always verify signatures. Verify the X-Webhook-Signature header on every request before processing any data. This is the only reliable way to confirm a request is genuinely from FluxStore.
2. Respond quickly. Return a 200 OK as soon as possible. Process the webhook data asynchronously if needed.
3. Handle duplicates. Use the X-Webhook-Id header for idempotency. The same event may be delivered more than once.
4. Use HTTPS. Always use an HTTPS endpoint to protect webhook data in transit.
5. Don’t rely on IP allowlisting alone. Requests come from Cloudflare’s IP ranges, which are shared across many services. Signature verification is the authoritative method of authentication.
6. Log everything. Keep your own logs of received webhooks for debugging and auditing.

For details on signing and verification, see Security & verification. For per-event payload shapes, browse the Events section.