Skip to main content

​
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
  }
}
FieldTypeDescription
typestringEvent type (e.g., invoice.paid)
timestampstringWhen the event occurred (RFC3339 format)
dataobjectEvent-specific payload

​
Supported Events

EventDescriptionUse Case
subscription.activatedSubscription becomes activeGrant product access
subscription.startedSubscription period startsReset usage counters
subscription.cancelation_scheduledCancellation scheduledSend retention offers
subscription.canceledSubscription endsRevoke product access
invoice.issuedInvoice finalizedSend custom notifications
invoice.paidInvoice fully paidConfirm continued access
payment.createdPayment initiatedTrack payment attempts
payment.updatedPayment status changedHandle success/failure
refund.updatedRefund status changedSync refund status
line_item.deletedLine item removedUpdate entitlements
checkout.session.completedCheckout completedProvision new customers
account.credits.grantedCredits added to accountTrack credit grants
account.credits.balance_depletedCredit balance reached zeroPrompt 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 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

  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: 
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:
AttemptDelay
1Immediate
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
810 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

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.