> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when billing events occur in Fluxrate.

Webhooks let you react to billing events in real time — invoice created, subscription canceled, payment received, and more.

## Incoming Webhooks

Fluxrate can receive webhooks from external services (payment gateways like Stripe, Razorpay) to automatically update invoice status when payments are processed.

Configure incoming webhook endpoints in **Dashboard → Webhooks**.

## Outgoing Webhooks

Fluxrate sends webhook notifications when key billing events occur.

### Event Types

| Event                    | Description                             |
| ------------------------ | --------------------------------------- |
| `invoice.created`        | A new invoice was created (DRAFT)       |
| `invoice.finalized`      | An invoice was finalized (DRAFT → OPEN) |
| `invoice.paid`           | An invoice was marked as paid           |
| `invoice.voided`         | An invoice was voided                   |
| `subscription.created`   | A new subscription was created          |
| `subscription.activated` | Trial ended, subscription became active |
| `subscription.canceled`  | A subscription was canceled             |

### Webhook Payload

```json theme={null}
{
  "event": "invoice.finalized",
  "timestamp": "2025-01-15T14:10:00Z",
  "data": {
    "invoice_id": "...",
    "invoice_number": "INV-2025-0055",
    "customer_id": "...",
    "total": 145.20,
    "currency": "USD",
    "status": "OPEN"
  }
}
```

## Configuring Outgoing Webhooks

1. Go to **Dashboard → Webhooks**
2. Click **Add Endpoint**
3. Enter your webhook URL
4. Select the events to receive
5. Save — Fluxrate will start delivering events

## Webhook Security

Validate webhook signatures to ensure events come from Fluxrate:

```python theme={null}
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

The signature is included in the `X-Fluxrate-Signature` header.

## Retry Policy

If your endpoint returns a non-2xx response, Fluxrate retries with exponential backoff:

| Attempt | Delay      |
| ------- | ---------- |
| 1       | 30 seconds |
| 2       | 2 minutes  |
| 3       | 10 minutes |
| 4       | 1 hour     |
| 5       | 6 hours    |

After 5 failed attempts, the delivery is marked as failed.

## Viewing Delivery History

Check delivery status in **Dashboard → Webhooks → Deliveries** to see:

* Which events were sent
* Delivery status and response codes
* Failed attempts and errors