cfw-autumn/apps/docs/mintlify/documentation/webhooks.mdx

---
title: "Webhooks"
description: "Receive real-time notifications when customer billing events occur"
---

With Autumn, you don't need webhooks for managing billing — subscription state, usage tracking, and access control are all synchronized automatically. 

However, webhooks can still be useful for specific use cases where you want to trigger actions in your own systems.

<Note>
Webhooks are currently in beta. Please reach out to us on [Discord](https://discord.gg/STqxY92zuS) or email us at support@useautumn.com to enable webhooks for your account.
</Note>

## Use Cases

While Autumn handles billing complexity for you, webhooks are helpful for:

- **Sending activation emails** — Welcome new subscribers or notify users when their plan changes
- **Triggering workflows** — Start onboarding sequences, provision resources, or update CRM records
- **Syncing with external systems** — Keep your database, analytics, or other tools in sync with subscription changes
- **Deprovisioning access to services** — Shut off access to downstream services when a customer cancels their subscription

## Available Events

### customer.products.updated

Fired when a customer's product or plan changes. The `scenario` field indicates what type of change occurred.

| Scenario | Description |
|----------|-------------|
| `new` | Customer subscribed to a new product |
| `upgrade` | Customer upgraded to a higher-tier plan |
| `downgrade` | Customer downgraded to a lower-tier plan |
| `renew` | Subscription renewed for another billing period |
| `cancel` | Subscription was canceled |
| `expired` | Subscription has expired |
| `past_due` | Payment is past due |
| `scheduled` | A plan change has been scheduled |

**Example payload:**

```json expandable
{
  "type": "customer.products.updated",
  "data": {
    "scenario": "new",
    "customer": {
      "id": "user_123",
      "name": "John Doe",
      "email": "john@example.com",
      "balances": { ... },
      "subscriptions": [ ... ]
    },
    "updated_product": {
      "id": "pro_plan",
      "name": "Pro Plan",
      "features": [ ... ]
    }
  }
}
```

### balances.limit_reached

Fired when a customer hits a usage limit for a feature. A limit can be the included allowance, a max purchase cap, or a spend limit.

| Limit Type | Description |
|------------|-------------|
| `included` | Customer has exhausted their included allowance |
| `max_purchase` | Customer has reached the maximum purchase cap for overage |
| `spend_limit` | Customer has hit their configured spend limit |

**Example payload:**

```json expandable
{
  "type": "balances.limit_reached",
  "data": {
    "customer_id": "user_123",
    "feature_id": "api_calls",
    "limit_type": "included"
  }
}
```

For entity-scoped usage, the payload will also include an `entity_id`:

```json expandable
{
  "type": "balances.limit_reached",
  "data": {
    "customer_id": "user_123",
    "feature_id": "api_calls",
    "entity_id": "team_456",
    "limit_type": "max_purchase"
  }
}
```

### billing.auto_topup_succeeded

Fired when an [auto top-up](/documentation/modelling-pricing/auto-top-ups) successfully grants additional prepaid balance. Useful for sending receipts, updating internal ledgers, or reconciling balance after a recharge.

For auto-charged top-ups, the event fires only after the Stripe invoice is `paid`. For `invoice_mode` top-ups, the event fires once credits are granted and the invoice is finalized — `invoice.status` will typically be `"open"` until the customer pays.

Use `invoice.stripe_id` as a stable dedupe key. The top-level `id` field (e.g. `evt_auto_topup_...`) is a unique identifier for the event itself.

**Example payload (auto-charge):**

```json expandable
{
  "type": "billing.auto_topup_succeeded",
  "id": "evt_auto_topup_2abc123",
  "occurred_at": 1761840000000,
  "data": {
    "customer_id": "user_123",
    "feature_id": "credits",
    "quantity_granted": 1000,
    "threshold": 500,
    "balance_after": 1450,
    "invoice_mode": false,
    "invoice": {
      "stripe_id": "in_1A2B3C4D5E6F",
      "status": "paid",
      "total": 1000,
      "currency": "usd",
      "hosted_invoice_url": "https://invoice.stripe.com/i/..."
    }
  }
}
```

**Example payload (invoice mode):**

```json expandable
{
  "type": "billing.auto_topup_succeeded",
  "id": "evt_auto_topup_3xyz456",
  "occurred_at": 1761840000000,
  "data": {
    "customer_id": "user_123",
    "feature_id": "credits",
    "quantity_granted": 1000,
    "threshold": 500,
    "balance_after": 1450,
    "invoice_mode": true,
    "invoice": {
      "stripe_id": "in_2G3H4I5J6K7L",
      "status": "open",
      "total": 1000,
      "currency": "usd",
      "hosted_invoice_url": "https://invoice.stripe.com/i/..."
    }
  }
}
```

### balances.usage_alert_triggered

Fired when a customer crosses a configured usage alert threshold. Usage alerts let you monitor when customers approach or exceed specific usage levels for a feature.

| Alert Threshold Type | Description |
|---------------------|-------------|
| `usage` | An absolute usage count was crossed |
| `usage_percentage` | A percentage of the usage allowance was crossed |

**Example payload:**

```json expandable
{
  "type": "balances.usage_alert_triggered",
  "data": {
    "customer_id": "user_123",
    "feature_id": "api_calls",
    "usage_alert": {
      "name": "80% usage warning",
      "threshold": 80,
      "threshold_type": "usage_percentage"
    }
  }
}
```

## Setup

Once webhooks are enabled for your account, you can configure your webhook endpoints in the Autumn dashboard:

<Steps>
  <Step title="Navigate to Developer Settings">
    Go to the **Developer** section in your Autumn dashboard and select the **Webhooks** tab.
  </Step>
  <Step title="Add an Endpoint">
    Click **Add Endpoint** and enter the URL where you want to receive webhook events.
  </Step>
  <Step title="Select Events">
    Choose which events you want to subscribe to. You can select all events or specific ones.
  </Step>
  <Step title="Save and Test">
    Save your endpoint configuration. You can use the **Send Test Event** button to verify your endpoint is receiving events correctly.
  </Step>
</Steps>

## Webhook Security

Autumn uses [Svix](https://www.svix.com/) for reliable webhook delivery. Each webhook request includes signature headers that you can use to verify the request is genuinely from Autumn:

- `svix-id` — Unique message identifier
- `svix-timestamp` — Timestamp of when the message was sent
- `svix-signature` — Signature for verifying authenticity

You can use the [Svix libraries](https://docs.svix.com/receiving/verifying-payloads/how) to easily verify webhook signatures in your application.

## Retry Policy

If your endpoint returns an error or is unavailable, Autumn will automatically retry the webhook with exponential backoff. You can view delivery attempts and retry failed webhooks from the dashboard.