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 for reliable delivery with automatic retries.

Webhook Format

All webhooks follow the Standard Webhooks specification:

{
  "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

{
  "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.

{
  "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.

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

Navigate to Settings → Webhooks in the dashboard
Click Add Endpoint
Enter your endpoint URL
Select which events to receive
Copy the signing secret for verification
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:

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.

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:

215.16.239
216.8.72
33.109.123

Best Practices

Respond Quickly

Return 2xx within 15 seconds. Process asynchronously if needed.

Handle Duplicates

Use event IDs for idempotency. Events may be delivered multiple times.

Verify Signatures

Always verify webhook signatures using the Svix SDK.

Log Everything

Log event IDs for debugging and audit trails.

Next Steps

Webhooks Quickstart

Step-by-step webhook integration guide.

Svix Documentation

Detailed Svix documentation.

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Webhooks

Webhooks

Webhook Format

Supported Events

Event Payloads

Subscription Events

Invoice Events

Payment Events

Checkout Events

Credit Events

Setting Up Webhooks

Responding to Webhooks

Verifying Webhook Signatures

Retry Policy

IP Whitelist

Best Practices

Respond Quickly

Handle Duplicates

Verify Signatures

Log Everything

Next Steps

Webhooks Quickstart

Svix Documentation

​Webhooks

​Webhook Format

​Supported Events

​Event Payloads

​Subscription Events

​Invoice Events

​Payment Events

​Checkout Events

​Credit Events

​Setting Up Webhooks

​Responding to Webhooks

​Verifying Webhook Signatures

​Retry Policy

​IP Whitelist

​Best Practices

Respond Quickly

Handle Duplicates

Verify Signatures

Log Everything

​Next Steps

Webhooks Quickstart

Svix Documentation

Webhooks

Webhook Format

Supported Events

Event Payloads

Subscription Events

Invoice Events

Payment Events

Checkout Events

Credit Events

Setting Up Webhooks

Responding to Webhooks

Verifying Webhook Signatures

Retry Policy

IP Whitelist

Best Practices

Next Steps