Webhooks

Webhooks are HTTP POST notifications Alguna sends to a URL you configure when something happens in your account — a subscription activates, an invoice is paid, a payment fails, a checkout completes, a credit balance runs out. Use them instead of polling to keep your product, CRM or data warehouse in step with billing: provision access on subscription.activated, revoke it on subscription.canceled, fulfil a purchase on checkout.session.completed. Delivery is through Svix, which signs every request and retries failed deliveries. The objects these events describe are explained in How Alguna works. For the dashboard walkthrough, see the Webhooks quick start.

Webhook payloads are camelCase, unlike API request and response bodies, which are snake_case. Identifiers in payloads are the same IDs the API returns.

Webhook format

Every delivery has the same envelope:

{
  "type": "invoice.paid",
  "timestamp": "2026-04-01T20:26:10Z",
  "data": {
    // event-specific payload
  }
}

Field	Type	Description
`type`	string	Event type, for example `invoice.paid`
`timestamp`	string	When the event occurred, RFC 3339
`data`	object	Event-specific payload

Supported events

Event	Fires when	Typical use
`approval_request.created`	Approval was requested from an approver. One event is sent per approver.	Notify approvers
`approval_request.approved`	An approver approved their approval request.	Track approval progress
`approval_request.rejected`	An approver rejected their approval request.	React to rejected quotes
`approval_flow.completed`	A quote's approval flow reached a terminal state.	Sync the final outcome
`checkout.session.completed`	A checkout session's payment succeeded, for both hosted and embedded checkout.	Fulfil the purchase
`account.credits.balance_depleted`	A customer's credit balance reached zero.	Prompt a purchase
`account.credits.granted`	Credits were added to a customer account.	Track grants
`invoice.paid`	An invoice was paid in full.	Confirm continued access
`invoice.issued`	An invoice was finalized and issued to the customer.	Custom notifications, accounting
`lineitem.deleted`	A line item was removed from an invoice.	Update entitlements
`payment.created`	A payment was initiated.	Track payment attempts
`payment.updated`	A payment changed status.	Handle success and failure
`refund.updated`	A refund changed status.	Sync refund state
`subscription.activated`	A subscription became active.	Grant product access
`subscription.started`	A subscription reached its contract start date.	Reset usage counters
`subscription.updated`	A top-level subscription attribute changed: name, contract dates, renewal or invoice settings, or metadata. Pricing changes are reported on subscription.version.updated.	Re-fetch the subscription
`subscription.version.updated`	A subscription version was created, updated or published. Pricing changes are reported here.	Fetch the version by ID
`subscription.cancelation_scheduled`	A cancellation was scheduled for a future date.	Retention outreach
`subscription.cancelation_reverted`	A scheduled cancellation was called off before taking effect.	Undo retention actions
`subscription.canceled`	A subscription ended.	Revoke product access
`subscription.pause_scheduled`	A pause was scheduled for a future date. Not enabled by default — contact us to turn it on.	Warn downstream systems
`subscription.pause_unscheduled`	A scheduled pause was called off before taking effect. Not enabled by default — contact us to turn it on.	Undo pause preparations
`subscription.paused`	A pause took effect. Not enabled by default — contact us to turn it on.	Suspend access
`subscription.resumed`	A subscription resumed after a pause. Not enabled by default — contact us to turn it on.	Restore access

Event payloads

Each event’s data object is documented under Webhooks in the sidebar: every field, its type, whether it can be null, the values it accepts, and an example. For the objects behind these events and what their statuses mean, see Payments, Refunds, Credits & wallets, and hosted and embedded checkout.

Setting up webhooks

In the dashboard, go to Settings → Connections → Developers → Webhooks
Add an endpoint with your URL
Select the events to receive
Copy the signing secret — you need it to verify deliveries
Save

Test the endpoint with a test delivery before relying on it. The dashboard also shows delivery history per endpoint.

Responding to webhooks

Return a 2xx status code within 15 seconds to acknowledge receipt. Queue any real work and process it asynchronously — a slow handler is retried as a failure. If your framework applies CSRF protection, exempt the webhook route. Deliveries can arrive more than once and out of order. Key your handling on the svix-id header (the delivery ID) or on the object ID plus timestamp, and treat every handler as idempotent.

Verifying signatures

Every delivery is signed following the Standard Webhooks specification and carries svix-id, svix-timestamp and svix-signature headers. Verify with the Svix library for your language, using the raw request body:

import { Webhook } from "svix";

const wh = new Webhook(process.env.ALGUNA_WEBHOOK_SECRET);

// rawBody must be the unparsed request body; headers the incoming HTTP headers
const event = wh.verify(rawBody, headers);

import os

from svix.webhooks import Webhook

wh = Webhook(os.environ["ALGUNA_WEBHOOK_SECRET"])

# raw_body must be the unparsed request body; headers the incoming HTTP headers
event = wh.verify(raw_body, headers)

Verification fails if the body was re-serialized before checking, or if the delivery is older than the library’s tolerance window. Libraries for Go, Ruby, Java, PHP and others, and a description of the scheme itself, are in the Svix verification guide.

Retry policy

Failed deliveries — a non-2xx response, a timeout, or a connection error — are retried with exponential backoff, starting seconds after the first failure and stretching to hours. If an endpoint fails every attempt for five days it is disabled; re-enable it from the dashboard once it is healthy again. Svix owns the delivery schedule and publishes the exact intervals in its retry documentation.

IP allow list

If your endpoint sits behind a firewall, allow the source addresses Svix publishes for its EU cluster. The current list is in the Svix IP documentation — it changes, so read it there rather than copying it into long-lived firewall config.

Best practices

Respond quickly

Acknowledge with a 2xx, then process asynchronously.

Handle duplicates

Deliveries can repeat. Make handlers idempotent on the delivery ID.

Verify every delivery

Reject anything that fails signature verification.

Re-fetch when it matters

Payloads are snapshots. For money-moving decisions, read the object from the API.

Next steps

Webhooks quick start

Set up an endpoint from the dashboard.

Developer quick start

Auth, first request, events and webhooks end to end.

Automations

React to events inside Alguna without an endpoint.

Svix documentation

Verification libraries and delivery details.

API Reference

Examples

SDKs

API Reference

Webhooks

Webhook format

Supported events

Event payloads

Setting up webhooks

Responding to webhooks

Verifying signatures

Retry policy

IP allow list

Best practices

Respond quickly

Handle duplicates

Verify every delivery

Re-fetch when it matters

Next steps

Webhooks quick start

Developer quick start

Automations

Svix documentation

​Webhook format

​Supported events

​Event payloads

​Setting up webhooks

​Responding to webhooks

​Verifying signatures

​Retry policy

​IP allow list

​Best practices

Respond quickly

Handle duplicates

Verify every delivery

Re-fetch when it matters

​Next steps

Webhooks quick start

Developer quick start

Automations

Svix documentation

Webhook format

Supported events

Event payloads

Setting up webhooks

Responding to webhooks

Verifying signatures

Retry policy

IP allow list

Best practices

Next steps