Developers

APIs, webhooks, SDKs, and usage metering integration

Developers need clean APIs, reliable webhooks, and easy-to-integrate metering. This guide covers the technical integration points that matter most.

---

What Developers Care About

Priority	Why It Matters
Clean API	Fast integration, fewer bugs
Reliable webhooks	Keep systems in sync
Usage metering	Bill customers accurately
Sandbox environment	Test without affecting production
Good documentation	Less time debugging

---

API Basics

Authentication

All API requests require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Get your API key at Settings → API Keys

Base URLs

Environment	URL
Production	https://api.alguna.io
Sandbox	https://api.sandbox.alguna.io

Limits

Limit	Value
Events per ingestion request	100
Properties per event	50
unique_id length	72 characters

A rate-limited request returns 429. The SDK raises it as a RateLimitError carrying retryAfter.

---

Key Integration Points

1. Customer Sync

Keep Alguna customers in sync with your user database:

Your System	Alguna
User signs up	Create customer via API
User updates profile	Update customer
User deletes account	Cancel subscriptions, optionally delete

Endpoint: POST /customers

2. Usage Metering

Send usage events to bill customers accurately:

Event	When to Send
API call	After each billable API request
Storage used	Daily or hourly snapshot
Active users	Daily count at midnight
Compute time	After job completion

Endpoint: POST /events

3. Subscription Management

Action	Endpoint
Create subscription	POST /subscriptions
Get subscription	GET /subscriptions/{id}
Activate subscription	POST /subscriptions/{id}/activate
Cancel subscription	POST /subscriptions/{id}/cancel

4. Entitlements Check

Check if a customer can access a feature:

Check	How
Active subscription?	GET /subscriptions?customer_id={id}&status=active
On specific plan?	Check planId in subscription response
Within usage limits?	Compare current usage to plan limits

---

Webhooks

Alguna sends webhooks to notify your systems of billing events.

Setup

1. Navigate to Settings → Webhooks
2. Add your endpoint URL
3. Select events to receive
4. Copy the signing secret

Webhook Events

Event	When It Fires
subscription.activated	Subscription becomes active
subscription.canceled	Subscription ended
invoice.issued	Invoice finalized
invoice.paid	Payment successful
payment.created	Payment initiated
payment.updated	Payment status changed
account.credits.granted	Credits granted to a customer
account.credits.balance_depleted	Credit balance exhausted

Verifying Signatures

Webhooks are signed using Standard Webhooks and delivered through Svix. Verify with the Svix library for your language rather than hand-rolling the check:

import { Webhook } from "svix";

const wh = new Webhook(process.env.WEBHOOK_SECRET);
const payload = wh.verify(requestBody, headers);

Verification uses the svix-id, svix-timestamp and svix-signature headers.

Retry Policy

Failed deliveries are retried on a backoff, then the endpoint is disabled. See Webhooks for the schedule.

---

Usage Metering

Sending Events

Send usage events as they occur:

Endpoint: POST /events

Field	Description
event_name	The event type, matching the billable metric it feeds
account	Alguna customer ID, or an alias you set on the customer
unique_id	Idempotency key, up to 72 characters
timestamp	RFC 3339 timestamp. Optional; defaults to now
properties	Flat key/value pairs for filtering and aggregation

Events are sent as a batch: {"events": [ ... ]}, up to 100 per request.

Best Practices

Practice	Why
Batch events	Send up to 100 per request rather than one at a time
Set unique_id	Prevents an event being counted twice on retry
Buffer locally	Queue events locally, send async
Timestamp accurately	Use event time, not send time

Deduplication

Set unique_id on every event. A resend carrying the same unique_id is not counted again:

Scenario	Key Strategy
API calls	Request ID
Jobs	Job ID + timestamp
Daily snapshots	Customer ID + date

---

Sandbox Testing

Getting Started

1. Log in to sandbox.alguna.io
2. Get sandbox API keys at Settings → API Keys
3. Use sandbox base URL: https://api.sandbox.alguna.io

Test Scenarios

Scenario	How to Test
Successful payment	Use test card 4242 4242 4242 4242
Failed payment	Use test card 4000 0000 0000 0002
Subscription lifecycle	Create, activate, upgrade, cancel
Usage billing	Ingest events, generate invoice
Webhooks	Use webhook.site or ngrok

---

Common Patterns

Provisioning on Subscription

1. Customer signs up in your app
2. Your app creates Alguna customer
3. Your app creates subscription
4. Webhook: subscription.activated
5. Your app enables features for customer

Usage-Based Billing

1. Customer uses your product
2. Your app sends usage events to Alguna
3. End of billing period
4. Alguna aggregates usage, generates invoice
5. Webhook: invoice.issued
6. Payment collected
7. Webhook: invoice.paid

Credit System

1. Customer buys credits
2. Webhook: account.credits.granted
3. Customer uses product
4. Your app decrements credits (or Alguna tracks usage)
5. Credits low: webhook or alert
6. Webhook: account.credits.balance_depleted

---

Key Resources

Billable Metrics

Define what usage to track.

Send Usage

Ingesting usage events.

Credits & Wallets

Pre-paid credit systems.

Subscriptions

Managing subscription lifecycle.

---

API Reference

API Overview

Authentication, rate limits, errors.

Ingest Events

Send usage events.

Webhooks

Event payloads and setup.

Customers API

Create and manage customers.

---

Related Quick Starts

AI & Infrastructure

Token-based and usage billing.

Self-Serve (PLG)

Checkout and upgrade flows.

Fintech & Payments

Transaction-based metering.

← Back to Quick Starts

See all quick start guides