Webhooks

Every webhook event Alguna sends, its payload, how to verify signatures, and the retry schedule.

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
invoice.overdue	An issued invoice passed its due date without being paid in full.	Dunning, restrict access
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

1. In the dashboard, go to Settings → Connections → Developers → Webhooks
2. Add an endpoint with your URL
3. Select the events to receive
4. Copy the signing secret — you need it to verify deliveries
5. 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:

Node

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);

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.