Webhooks

Webhooks allow you to receive events as they happen. When an event occurs, Flux sends an HTTP POST request to your configured endpoint with the event payload.

Creating a Webhook

You can create webhooks via the dashboard or API:

Dashboard
API
SDK

Go to Settings → Webhooks
Click Add Endpoint
Enter your endpoint URL
Select the event types to subscribe to
Click Create

curl -X POST https://api.flux.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/flux",
    "events": ["order.completed", "user.signup"]
  }'

const webhook = await flux.webhooks.create({
  url: 'https://api.yourapp.com/webhooks/flux',
  events: ['order.completed', 'user.signup']
});

console.log('Webhook created:', webhook.id);
console.log('Signing secret:', webhook.secret);

Webhook Payload

When an event is delivered, your endpoint receives a POST request:

{
  "id": "evt_1a2b3c4d",
  "type": "order.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "orderId": "ord_8x7kj2",
    "amount": 9900,
    "currency": "usd",
    "customerId": "cus_abc123"
  }
}

Verifying Signatures

Every webhook request includes a signature header. Always verify this signature to ensure the request came from Flux.

import { Flux } from '@flux/node';

app.post('/webhooks/flux', (req, res) => {
  const signature = req.headers['flux-signature'];
  const payload = req.body;

  try {
    const event = flux.webhooks.verify(payload, signature, webhookSecret);
    
    switch (event.type) {
      case 'order.completed':
        handleOrderCompleted(event.data);
        break;
      case 'user.signup':
        handleUserSignup(event.data);
        break;
    }

    res.status(200).send('OK');
  } catch (err) {
    console.error('Invalid signature');
    res.status(400).send('Invalid signature');
  }
});

Never process webhooks without verifying the signature. This prevents attackers from sending fake events to your endpoint.

Retry Policy

If your endpoint returns a non-2xx status code or times out, Flux retries the delivery:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the event is marked as failed and you’ll receive an alert.

Testing Locally

Use the Flux CLI to forward webhooks to your local development server:

flux listen --forward-to localhost:3000/webhooks/flux

This creates a temporary public URL and forwards all webhook events to your local server.

Getting Started

Guides

Creating a Webhook

Webhook Payload

Verifying Signatures

Retry Policy

Testing Locally

Next Steps

Event Types

Webhook API

​Creating a Webhook

​Webhook Payload

​Verifying Signatures

​Retry Policy

​Testing Locally

​Next Steps

Event Types

Webhook API

Creating a Webhook

Webhook Payload

Verifying Signatures

Retry Policy

Testing Locally

Next Steps