Webhooks
Webhooks send real-time notifications to your server when events occur in Floatless.
When should I read this?
Read this if you need to react to billing events in real-time, such as successful payments or subscription changes.
How webhooks work
- Event occurs in Floatless (e.g., invoice paid)
- Floatless sends HTTP POST to your endpoint
- Your server processes the event
- Respond with 200 OK
Setting up webhooks
- Go to Settings → Webhooks
- Click "Add Endpoint"
- Enter your endpoint URL
- Select events to receive
- Copy the signing secret
Event types
Invoices
| Event | Description |
|---|---|
invoice.created |
Invoice created |
invoice.posted |
Invoice finalized and sent |
invoice.paid |
Payment received |
invoice.overdue |
Invoice past due date |
invoice.voided |
Invoice canceled |
Subscriptions
| Event | Description |
|---|---|
subscription.created |
New subscription started |
subscription.updated |
Subscription modified |
subscription.canceled |
Subscription ended |
subscription.paused |
Subscription paused |
subscription.resumed |
Subscription resumed |
Payments
| Event | Description |
|---|---|
payment.succeeded |
Payment successful |
payment.failed |
Payment failed |
payment.refunded |
Payment refunded |
Customers
| Event | Description |
|---|---|
customer.created |
Customer created |
customer.updated |
Customer modified |
customer.deleted |
Customer removed |
Webhook payload
{
"id": "evt_abc123",
"type": "invoice.paid",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"id": "inv_abc123",
"customer_id": "cus_abc123",
"amount_paid": 9900,
"status": "paid"
}
}
Verifying signatures
Verify webhooks are from Floatless using the signature header:
const signature = req.headers['floatless-signature'];
const payload = req.body;
const secret = process.env.WEBHOOK_SECRET;
const isValid = floatless.webhooks.verify(payload, signature, secret);
Best practices
- Respond quickly — return 200 within 5 seconds, process async
- Handle duplicates — use event ID for idempotency
- Retry logic — Floatless retries failed deliveries
- Secure endpoint — verify signatures, use HTTPS
Retry behavior
Failed webhook deliveries are retried:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 24 hours |
After 5 failures, the webhook is marked as failed and not retried.