Webhooks

BotShield delivers verification events to your endpoint via Svix. Each delivery is cryptographically signed — you verify the signature with your endpoint’s signing secret, exactly as shown below. This is the recommended way to receive results; polling verification/status is supported but adds latency and cost.

Anonymous by construction

Census performs one operation: anonymous human attestation — one operation, no modes. No identity ever crosses the boundary — verification payloads carry no email, no auth_mode, no BotShield user id, and no identity-bearing token. You learn that a human verified, never who. Rows correlate to your own system by request_id (and the metadata you supplied). To attach a known identity on your side, key off the request_id you generated when you created the verification.

Event Types

Event (`type`)	When it fires
`census.human_verified`	A fresh Face ID / passkey attestation completed for this request
`census.multipass_active`	A returning human resolved via MultiPass continuity at the precheck — no fresh challenge was needed
`census.human_unavailable`	Verification could not complete — the user denied/cancelled, the flow errored, or the link TTL lapsed without a response

There are exactly three events. census.human_unavailable merges the former failed and expired cases — distinguish them by the payload (failed_at + reason for a denial/error vs. expired_at for a TTL lapse). Exactly one event fires per verification request. Once delivered, the request is terminal — no further events fire for that request_id.

Result states in the webhook. Census exposes three result states — Human Verified, MultiPass Active, and Human Unavailable — and the webhook now carries its own event for each: Human Verified = census.human_verified, MultiPass Active = census.multipass_active, Human Unavailable = census.human_unavailable. MultiPass Active no longer collapses into Human Verified — webhook-only partners receive census.multipass_active directly, mirroring the embed’s synchronous botshield:multipass-status distinction. Human Unavailable covers both denial/error and TTL expiry; tell them apart by the payload fields (failed_at + reason vs. expired_at).

Payloads

event_id is the same value as request_id — both are the req_<hex> attestation id. They are aliases for the one identifier; dedupe on either.

`census.human_verified`

{
  "type": "census.human_verified",
  "event_id": "req_xyz789...",
  "request_id": "req_xyz789...",
  "verified_at": "2026-06-16T12:00:00Z",
  "product": "census",
  "metadata": { "order_id": "checkout-12345" }
}

`census.multipass_active`

A returning human resolved via MultiPass continuity at the precheck — no fresh challenge was issued. Same anonymous payload shape as census.human_verified; this is the webhook-only mirror of the embed’s synchronous MultiPass Active result.

{
  "type": "census.multipass_active",
  "event_id": "req_xyz789...",
  "request_id": "req_xyz789...",
  "verified_at": "2026-06-16T12:00:00Z",
  "product": "census",
  "metadata": { "order_id": "checkout-12345" }
}

`census.human_unavailable`

Fires on a denial/error (carries failed_at + reason) or on a TTL lapse (carries expired_at). The two cases are distinguished by which timestamp is present. Denied / errored:

{
  "type": "census.human_unavailable",
  "event_id": "req_xyz789...",
  "request_id": "req_xyz789...",
  "failed_at": "2026-06-16T12:00:12Z",
  "reason": "user_denied",
  "error_message": "Verification failed",
  "product": "census",
  "metadata": { "order_id": "checkout-12345" }
}

reason is one of: user_denied, device_lock_required, internal_error, platform_declined. Expired (link TTL lapsed — default 10 minutes):

{
  "type": "census.human_unavailable",
  "event_id": "req_xyz789...",
  "request_id": "req_xyz789...",
  "expired_at": "2026-06-16T12:10:00Z",
  "product": "census",
  "metadata": { "order_id": "checkout-12345" }
}

Fields

Field	Type	Description
`type`	string	The event name — `census.human_verified` \| `census.multipass_active` \| `census.human_unavailable`
`event_id`	string	The attestation id — the same `req_…` value as `request_id` (alias). Dedupe on it for idempotency.
`request_id`	string	The verification request ID you received when you created the link — your join key
`verified_at` / `failed_at` / `expired_at`	string	ISO 8601 timestamp of the state change. For `census.human_unavailable`, `failed_at` (with `reason`) or `expired_at` tells the two cases apart.
`reason`	enum	(`human_unavailable` denial/error only) `user_denied` \| `device_lock_required` \| `internal_error` \| `platform_declined`
`product`	string	`census` \| `drop` \| `q`
`metadata`	object or null	Whatever `metadata` you included when creating the verification link — round-tripped back

Get your signing secret

In the Console → Settings → Webhooks, open the webhooks portal.
Add an endpoint with your HTTPS URL (e.g. https://yourapp.com/api/botshield-webhook).
Copy that endpoint’s Signing Secret — it starts with whsec_. Store it as an environment variable; treat it like a password.

Each endpoint has its own secret. From the same portal you can send test events, inspect delivery logs, and replay failed deliveries.

Verify the signature (server-side)

Every delivery includes three headers — svix-id, svix-timestamp, svix-signature — and is signed with your endpoint’s whsec_ secret. Verify with the official svix library. You must pass the raw, unparsed request body to the verifier (a re-serialized JSON object will not match the signature).

Node / Express

import express from "express";
import { Webhook } from "svix";

const app = express();
const SIGNING_SECRET = process.env.BOTSHIELD_WEBHOOK_SECRET!; // whsec_...

// IMPORTANT: capture the raw body for this route — do NOT use express.json() here.
app.post(
  "/api/botshield-webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const wh = new Webhook(SIGNING_SECRET);

    let evt: any;
    try {
      // Throws if the signature is invalid or the timestamp is out of tolerance.
      evt = wh.verify(req.body, {
        "svix-id": req.header("svix-id")!,
        "svix-timestamp": req.header("svix-timestamp")!,
        "svix-signature": req.header("svix-signature")!,
      });
    } catch {
      return res.status(400).send("invalid signature");
    }

    // Idempotency — BotShield may retry. Dedupe before acting.
    if (await alreadyProcessed(evt.event_id)) return res.sendStatus(200);
    await markProcessed(evt.event_id);

    switch (evt.type) {
      case "census.human_verified":
        // A fresh Face ID / passkey attestation completed.
        // Correlate to your order via request_id / metadata.
        await onVerified(evt.request_id, evt.metadata);
        break;
      case "census.multipass_active":
        // A returning human resolved via MultiPass continuity — no fresh
        // challenge. Treat as a pass, same as human_verified.
        await onVerified(evt.request_id, evt.metadata);
        break;
      case "census.human_unavailable":
        // Could not complete. Distinguish denial/error from TTL expiry by
        // which timestamp is present.
        if (evt.expired_at) {
          await onExpired(evt.request_id);
        } else {
          await onFailed(evt.request_id, evt.reason); // failed_at + reason
        }
        break;
    }

    return res.sendStatus(200); // ack (empty body is fine)
  }
);

The svix library is also available for Python, Go, Rust, Java/Kotlin, Ruby, C#, and PHP — the verification call is identical in shape (Webhook(secret).verify(rawBody, headers)). See the Svix docs for per-language snippets.

Why the signature, not a token? Authenticity comes from the Svix envelope signature over the whole payload — there is no identity-bearing token to validate, and nothing in the body to decode for a user. Verify the signature, then trust the type + request_id.

Idempotency, delivery & retries

Idempotency — dedupe on event_id (or the svix-id header). Retries reuse the same id.
Acknowledge with any 2xx (empty body fine). Non-2xx triggers retries with exponential backoff.
Inspect & replay — every attempt is logged in the Console webhooks portal; you can replay failed deliveries there.

Human Presence — the verdict + reason model and the user-facing result states
Trusted Account Signal — how linked verified accounts strengthen MultiPass durability (internal UUID, never identity)

Get Started

Client SDK Embed

Server SDK

Integration Guides

Deployment

Queue (Q)

Concepts

Webhooks — Payloads & Verification

Webhooks

Anonymous by construction

Event Types

Payloads

`census.human_verified`

`census.multipass_active`

`census.human_unavailable`

Fields

Get your signing secret

Verify the signature (server-side)

Node / Express

Idempotency, delivery & retries

​Webhooks

​Anonymous by construction

​Event Types

​Payloads

​census.human_verified

​census.multipass_active

​census.human_unavailable

​Fields

​Get your signing secret

​Verify the signature (server-side)

​Node / Express

​Idempotency, delivery & retries

​Related

Webhooks

Anonymous by construction

Event Types

Payloads

`census.human_verified`

`census.multipass_active`

`census.human_unavailable`

Fields

Get your signing secret

Verify the signature (server-side)

Node / Express

Idempotency, delivery & retries

Related