Quickstart

This walks you from zero to a verified webhook in four steps. The example runs a business-redacted age check (age_verify), but the flow is identical for any primitive.

Publish a workflow + configure delivery

Create a workflow with one age_verify step and set its threshold to 21.
Choose API only, configure a signed webhook, and publish revision 1.
Copy the workflow id and an API key (alentra_...).

A webhook URL is required. Webhooks are the primary result channel; the session GET exists only for one-off reconciliation, not polling. A session won’t be created until your business has a webhook configured. You’ll also need your webhook signing secret (alentra_whsec_...) from the dashboard to verify deliveries (step 4).

Create a session

Server-to-server, with your API key. Pass the published workflow_id plus any string-valued correlation metadata for this run.

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_age_gate",
    "metadata": { "order_id": "order_4815" }
  }'

const res = await fetch("https://api.alentra.app/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALENTRA_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    workflow_id: "wf_age_gate",
    metadata: { order_id: "order_4815" }
  })
});
const session = await res.json();

Alentra returns the session and its hosted URL:

{
  "id": "sess_abc123",
  "status": "created",
  "workflow_id": "wf_age_gate",
  "workflow_revision": 1,
  "url": "https://alentra.app/s/sess_abc123",
  "expires": "2026-06-07T12:34:56Z"
}

Send the user to the hosted page

Hand the user session.url. Alentra’s hosted page invokes the W3C Digital Credentials API; the browser owns the same-device or cross-device handoff. Do not call Alentra’s hosted-page transport endpoints or build a polling/QR protocol of your own.

Receive the signed result

When the wallet responds and Alentra verifies it, you get a POST to your webhook URL — one logical step.completed per step plus a terminal session.* event. Network retries can change arrival order.

POST /your-webhook
X-Alentra-Event: step.completed
X-Alentra-Timestamp: 1749300000
X-Alentra-Signature: 9f86d081884c7d65...
X-Alentra-Delivery-Id: sess_abc123:step.completed:0

{
  "event": "step.completed",
  "delivery_id": "sess_abc123:step.completed:0",
  "sent": "2026-07-13T12:01:30Z",
  "data": {
    "session_id": "sess_abc123",
    "workflow": {
      "id": "wf_age_gate",
      "name": "Age gate",
      "revision": 1
    },
    "metadata": { "order_id": "order_4815" },
    "stage": 0,
    "primitive": "age_verify",
    "audit_id": "sess_abc123_0",
    "satisfied": true,
    "min_age": 21
  }
}

Always verify the signature before trusting a delivery:

import crypto from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-alentra-timestamp"];
  const sig = req.headers["x-alentra-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.`)
    .update(req.rawBody) // raw bytes, not re-serialized JSON
    .digest();
  const provided = Buffer.from(sig ?? "", "hex");
  return provided.length === expected.length &&
    crypto.timingSafeEqual(provided, expected);
}

import hmac, hashlib

def verify(timestamp: str, raw_body: bytes, signature: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), signature)

Compose multiple steps

Real flows often need more than one verified action—for example, identify the signer, then sign the contract. Add both primitives to the workflow builder and drag them into the order you want before publishing. Every run snapshots that exact revision. Alentra creates one logical webhook per step; use stage and the stable delivery id because retries can arrive late or out of order.

Workflow revision 3
1. identify — first_name, last_name, country
2. sign — documents supplied for each run

A reusable workflow never stores run documents. When an API-only workflow contains sign, create each session as multipart/form-data: send workflow_id and one named file part per document. See Primitives → sign.

Choose a test mode

Before creating a deployed session, open the business’s Coverage page in the Alentra dashboard. Sandbox businesses begin with Utopia selected. Production businesses begin with no usable route: select the routes and submit the reusable provider packet; Alentra handles Google registration and keeps every unapproved route fail-closed.

Local development: run the service with ENVIRONMENT unset and the web app in its development build. The hosted page then exposes Simulate, and backend issuer trust is relaxed. These results are for development only.
Google Sandbox: ENVIRONMENT=SANDBOX uses Google’s published request signer, RP metadata, Utopia ID Pass profile, and sandbox IACA. It runs the real encrypted wallet path with strict sandbox issuer trust; install a Utopia test ID in Google Wallet first.
Production: ENVIRONMENT=PRODUCTION accepts only ledger routes explicitly promoted to live, with provider credentials and authenticated issuer roots for each exact credential profile.

The API and webhook contract are identical in all three modes. See Wallets & environments.

Next steps

Primitives

Every primitive’s parameters and result shape.

Sessions

Lifecycle, gates (continue/stop), binding, and expiry.

Webhooks

Every event, payload, and signature verification.

Create a session

The full request reference, including all options.

Getting Started

Core Concepts

Compose multiple steps

Choose a test mode

Next steps

Primitives

Sessions

Webhooks

Create a session

​Compose multiple steps

​Choose a test mode

​Next steps

Primitives

Sessions

Webhooks

Create a session

Compose multiple steps

Choose a test mode

Next steps