158 lines
5.1 KiB
Plaintext
158 lines
5.1 KiB
Plaintext
---
|
|
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"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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.
|