Use browser status for UX. Use webhooks and signed results for backend state changes.
Authbound delivers webhook events at least once and retries failed deliveries with exponential backoff.
On Next.js, createAuthboundHandlers can run an onWebhook callback on the same route as verification creation when you pass a second options argument (see the @authbound/server package README in authbound-sdk). For a dedicated endpoint, verify signatures as below.
Verify webhook signatures
import { verifyWebhookSignatureDetailed } from "@authbound/server";
export async function POST(request: Request) {
const payload = await request.text();
const signature = request.headers.get("x-authbound-signature");
if (!signature) {
return new Response("Missing signature", { status: 401 });
}
const verification = verifyWebhookSignatureDetailed({
payload,
signature,
secret: process.env.AUTHBOUND_WEBHOOK_SECRET!,
tolerance: 300,
});
if (!verification.valid) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(payload);
if (event.type === "verification.completed") {
await handleVerificationCompleted(event.data.object);
}
return Response.json({ received: true });
}
Webhook events include api_version and contract_revision alongside the event type. Use contract_revision when a consumer pins or audits the payload contract.
Fetch a signed result
Webhooks never carry the claims a wallet disclosed. Your server pulls them from the signed result with its secret key. They’re readable for 15 minutes after the verification finishes. After that, claimsStatus is expired and only the token’s digest of them remains.
import { AuthboundClient, meetsMinimumAge } from "@authbound/server";
const authbound = new AuthboundClient({
apiKey: process.env.AUTHBOUND_SECRET_KEY!,
apiUrl: process.env.AUTHBOUND_API_URL!,
});
const result = await authbound.verifications.getResult("vrf_...");
if (result.claimsStatus === "available" && meetsMinimumAge(result.claims, 18)) {
await markAgeVerified(result.verificationId);
}
claimsStatus is available while claims and claimsSalt are present, expired after the 15 minutes, and none when the policy returns no claims. Claims are keyed by the paths the wallet disclosed. For “Age 18+”, that’s { "eu.europa.ec.av.1": { age_over_18: true } }, { age_equal_or_over: { "18": true } }, or { birthdate: "..." }. meetsMinimumAge accepts all three.
Keep claims as evidence
To store claims and prove later that Authbound signed for them, keep the result token and the claims salt with them. Verify the token against your deployment’s /v1/jwks, then check the claims against its digest:
import { verifyClaimsDigest } from "@authbound/server";
const resultToken = await authbound.verifications.verifyResultToken(
stored.resultToken,
{ verificationId: stored.verificationId }
);
const signedForThese = await verifyClaimsDigest(
stored.claims,
stored.claimsSalt,
resultToken
);
verifyResultToken checks the ES256 signature, the issuer, that the token is for this verification, and its expiry, and throws ResultTokenVerificationError otherwise. Result tokens are valid for one hour from each read. Set resultIssuer on the client when your deployment signs with an issuer other than the origin of apiUrl.
Common events
| Event | Use |
|---|
verification.completed | Mark the user or workflow as verified. |
verification.failed | Store failure state and let the user retry when appropriate. Failed event payloads include a failure_code. |
verification.canceled | Clear pending state and let the user retry. |
verification.expired | Store timeout state and let the user restart verification. |
verification.state_changed | Track non-terminal lifecycle changes for audit or support. |
Failed verification objects carry a failure_code (for example user_declined, policy_not_satisfied, wallet_error). Non-failed objects do not include one. See verification overview for the full list.
Retry handling
Webhook handlers should be idempotent. Use the event ID or verification ID as the dedupe key, and make database writes safe to retry.
await db.verificationEvents.upsert({
where: { eventId: event.id },
create: {
eventId: event.id,
verificationId: event.data.object.id,
type: event.type,
},
update: {},
});
Never trust a webhook without checking its signature. Treat unsigned requests as unauthenticated internet traffic.
Returned claims
Webhook payloads never carry claim values. Read the disclosed claims with a secret key from GET /v1/verifications/{id}/result: a verified result returns claims_status and, while claims_status is available, the claims the policy requested, exactly as the wallet disclosed them. Results stay readable for a short window after the verification ends, then report expired. Failed results never include claims.
If you write test fixtures for your webhook handler, include api_version: "v1" and contract_revision. Webhook events always carry the latest contract revision, currently v1.2026-10-24.1. The event shape is the same in every supported revision.