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:
- 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 |
Testing Locally
Use the Flux CLI to forward webhooks to your local development server:
flux listen --forward-to localhost:3000/webhooks/flux
Next Steps
