> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
# Webhooks
Alguna provides webhooks to notify you about events that happen in your account. Use webhooks to receive real-time notifications when customers subscribe, invoices are paid, payments fail, and more.
Webhooks are delivered via [Svix](https://www.svix.com/) for reliable delivery with automatic retries.
***
## Webhook Format
All webhooks follow the [Standard Webhooks specification](https://www.standardwebhooks.com/):
```json theme={null}
{
"type": "invoice.paid",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
// Event-specific payload
}
}
```
| Field | Type | Description |
| ----------- | ------ | ---------------------------------------- |
| `type` | string | Event type (e.g., `invoice.paid`) |
| `timestamp` | string | When the event occurred (RFC3339 format) |
| `data` | object | Event-specific payload |
***
## Supported Events
| Event | Description | Use Case |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `subscription.activated` | Subscription becomes active | Grant product access |
| `subscription.started` | Subscription period starts | Reset usage counters |
| `subscription.updated` | A top-level subscription attribute changed (name, contract dates, renewal settings, invoice settings, metadata, etc.) | Re-fetch the subscription to sync state |
| `subscription.version.updated` | A specific subscription version was created, updated, or published (pricing changes live here) | Fetch the version by id to read full details |
| `subscription.cancelation_scheduled` | Cancellation scheduled | Send retention offers |
| `subscription.canceled` | Subscription ends | Revoke product access |
| `invoice.issued` | Invoice finalized | Send custom notifications |
| `invoice.paid` | Invoice fully paid | Confirm continued access |
| `payment.created` | Payment initiated | Track payment attempts |
| `payment.updated` | Payment status changed | Handle success/failure |
| `refund.updated` | Refund status changed | Sync refund status |
| `line_item.deleted` | Line item removed | Update entitlements |
| `checkout.session.completed` | Checkout completed | Provision new customers |
| `account.credits.granted` | Credits added to account | Track credit grants |
| `account.credits.balance_depleted` | Credit balance reached zero | Prompt credit purchase |
***
## Event Payloads
### Subscription Events
**subscription.activated**
```json theme={null}
{
"type": "subscription.activated",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"name": "Enterprise Plan",
"status": "active",
"currency": "USD",
"contractStartDate": "2024-01-01T00:00:00Z",
"contractEndDate": "2025-01-01T00:00:00Z",
"activatedAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-24T16:36:52Z",
"updatedAt": "2024-01-26T19:30:37Z"
}
}
```
**subscription.updated**
Emitted when a top-level subscription attribute changes — name, contract dates, renewal settings, invoice settings, metadata, and similar. Pricing/version changes are not covered by this event; listen for `subscription.version.updated` for those.
```json theme={null}
{
"type": "subscription.updated",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"name": "Enterprise Plan",
"status": "active",
"currency": "USD",
"contractStartDate": "2024-01-01T00:00:00Z",
"contractEndDate": "2025-01-01T00:00:00Z",
"activatedAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-24T16:36:52Z",
"updatedAt": "2024-08-03T20:26:10Z"
}
}
```
**subscription.version.updated**
Emitted when a specific subscription version is created, updated, or published. The payload is intentionally thin — only identifiers and status. Fetch the version by id if you need full details.
```json theme={null}
{
"type": "subscription.version.updated",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "qv_ZVzWRFnt",
"subscriptionId": "sub_aBsZxlLh",
"accountId": "acc_pQrStUvW",
"status": "published"
}
}
```
Version status values: `draft`, `published`
Subscription status values: `draft`, `active`, `canceled`
### Invoice Events
**invoice.issued / invoice.paid**
```json theme={null}
{
"type": "invoice.issued",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"currency": "USD",
"description": "Platform subscription",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "issued",
"total": "200.00",
"createdAt": "2024-01-24T16:36:52Z",
"updatedAt": "2024-01-26T19:30:37Z"
}
}
```
### Payment Events
**payment.created / payment.updated**
```json theme={null}
{
"type": "payment.updated",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"invoiceId": "dfTDjGsA",
"currency": "USD",
"amount": "200.00",
"status": "completed",
"createdAt": "2024-01-24T16:36:52Z",
"updatedAt": "2024-01-26T19:30:37Z"
}
}
```
Payment status values:
* `pending_client_action` - Requires customer action
* `pending_authorization` - Awaiting authorization
* `processing` - Being processed
* `completed` - Successfully processed
* `failed` - Payment failed
### Checkout Events
**checkout.session.completed**
```json theme={null}
{
"type": "checkout.session.completed",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"id": "cs_abc123",
"accountId": "aBsZxlLh",
"subscriptionId": "ZVzWRFnt",
"status": "complete",
"amountTotal": "107.91",
"currency": "USD",
"completedAt": "2024-01-20T10:35:00Z"
}
}
```
### Credit Events
**account.credits.granted**
```json theme={null}
{
"type": "account.credits.granted",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"accountId": "aBsZxlLh",
"grantId": "cg_ZVzWRFnt",
"amount": "100.00",
"type": "monetary",
"reason": "Customer loyalty bonus"
}
}
```
**account.credits.balance\_depleted**
```json theme={null}
{
"type": "account.credits.balance_depleted",
"timestamp": "2024-08-03T20:26:10Z",
"data": {
"accountId": "aBsZxlLh",
"amount": "0",
"type": "monetary"
}
}
```
Credit type values: `monetary`, `units`
***
## Setting Up Webhooks
1. Navigate to **Settings → Webhooks** in the dashboard
2. Click **Add Endpoint**
3. Enter your endpoint URL
4. Select which events to receive
5. Copy the signing secret for verification
6. Save
***
## Responding to Webhooks
Return a 2xx status code (200-299) within 15 seconds to acknowledge receipt.
If using a framework with CSRF protection, disable it for your webhook endpoint.
***
## Verifying Webhook Signatures
Always verify webhook signatures to ensure they're from Alguna. Use the Svix SDK:
```javascript theme={null}
import { Webhook } from "svix";
const wh = new Webhook(process.env.WEBHOOK_SECRET);
// Verify the webhook
const payload = wh.verify(requestBody, headers);
```
Headers used for verification:
* `svix-id`
* `svix-timestamp`
* `svix-signature`
For complete documentation in all languages (Node.js, Python, Go, Ruby, Java, etc.), see the [Svix verification guide](https://docs.svix.com/receiving/verifying-payloads/how).
***
## Retry Policy
Failed webhook deliveries are retried with exponential backoff:
| Attempt | Delay |
| ------- | ---------- |
| 1 | Immediate |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 10 hours |
If all attempts fail for 5 days, the endpoint is disabled.
***
## IP Whitelist
If your endpoint is behind a firewall, allow these Svix IP addresses:
```
52.215.16.239
54.216.8.72
63.33.109.123
```
***
## Best Practices
Return 2xx within 15 seconds. Process asynchronously if needed.
Use event IDs for idempotency. Events may be delivered multiple times.
Always verify webhook signatures using the Svix SDK.
Log event IDs for debugging and audit trails.
***
## Next Steps
Step-by-step webhook integration guide.
Detailed Svix documentation.