Webhooks

Webhooks are how Stile tells your server that something happened — a session verified, a manual review resolved, a trust-reuse grant revoked — without you polling for it. This guide is the canonical reference for receiving webhooks: registering an endpoint, verifying signatures, handling retries and duplicates, and testing locally.

How delivery works

When an event occurs, Stile sends an HTTP POST with a signed JSON payload to every endpoint subscribed to that event type. Your endpoint acknowledges with a 2xx response; anything else (or a timeout) triggers the retry schedule.

Your endpoint must meet three requirements:

• Publicly accessible HTTPS URL. Plain HTTP is allowed in sandbox / local testing only.
• Respond with 2xx within 30 seconds. Slower responses count as failures.
• Live orgs require at least one active webhook endpoint before sessions can be created — POST /v1/verification_sessions returns 400 webhook_required otherwise. Sandbox orgs are exempt.

Beyond the session lifecycle (verification_session.*), events also fire for manual review outcomes (session_review.*) and trust-reuse grants and consent revocations (trust_reuse_grant.*, trust_reuse_consent.*) — see the full event-type catalog.

Setup

curl -X POST https://api.stile.id/v1/webhook_endpoints \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/api/webhooks",
    "enabled_events": ["verification_session.verified", "verification_session.failed"]
  }'

const endpoint = await stile.webhookEndpoints.create({
  url: "https://yourapp.com/api/webhooks",
  enabled_events: ["verification_session.verified", "verification_session.failed"],
});

import Stile from "@stile/node";

const stile = new Stile(process.env.STILE_API_KEY!);

export async function POST(req: Request) {
  let event;
  try {
    event = await stile.webhooks.fromRequest(req, process.env.WEBHOOK_SECRET!);
  } catch (err) {
    console.error("Webhook signature verification failed:", err);
    return new Response("Invalid signature", { status: 400 });
  }

  switch (event.type) {
    case "verification_session.verified":
      await handleVerified(event.data);
      break;
    case "verification_session.failed":
      await handleFailed(event.data);
      break;
    case "verification_session.expired":
      await handleExpired(event.data);
      break;
  }

  return Response.json({ received: true });
}

Payload and headers

Every delivery is an HTTP POST carrying a JSON event object and these headers (HTTP header names are case-insensitive; most frameworks expose them lowercase, e.g. stile-signature):

The body is an event object whose data is a snapshot of the verification session at the moment the event fired:

{
  "id": "evt_abc123",
  "object": "event",
  "type": "verification_session.verified",
  "created": 1741564800,
  "data": {
    "id": "vks_xyz789",
    "object": "verification_session",
    "status": "verified",
    "type": "identity",
    "client_reference_id": "user_123",
    "expires_at": 1741651200,
    "completed_at": 1741564800,
    "created": 1741561200
  }
}

Retries of the same event arrive with the same event id but a new delivery ID — deduplicate on event.id, not on Stile-Webhook-Id.

Signature verification

The Stile-Signature header has the format t={timestamp},v1={signature}, where the signature is an HMAC-SHA256 over {timestamp}.{raw_body} keyed with your endpoint secret. Always verify it before processing the event; signatures with a timestamp older than 5 minutes are rejected to prevent replay.

Using fromRequest() (recommended)

The handler in Setup above shows the full pattern: pass the Web API Request plus your secret, and fromRequest() reads the raw body, checks the timestamp, and verifies the HMAC in one call.

Using constructEvent() (low-level)

If your framework doesn't use the standard Request object, use constructEvent() directly with the raw body and signature header:

const event = stile.webhooks.constructEvent(
  rawBody, // string or Buffer — the unmodified request body
  signatureHeader, // the stile-signature header value
  webhookSecret, // your endpoint's signing secret
);

Both methods throw WebhookSignatureError on failure — respond 400 in every case:

Best practices

Retry behavior

If your endpoint returns a non-2xx response or doesn't respond within 30 seconds, Stile retries the delivery with exponential backoff:

After the final attempt (roughly 10.5 hours from the initial delivery), the delivery is marked as permanently failed. Failed deliveries stay visible in the dashboard and the deliveries API, and can be retried manually once your endpoint is healthy again.

Handling duplicates

Due to retries, your endpoint may receive the same event more than once. Use the event id to deduplicate:

const alreadyProcessed = await db.processedEvents.findUnique({
  where: { eventId: event.id },
});

if (alreadyProcessed) {
  return Response.json({ received: true }); // Acknowledge but skip
}

await handleEvent(event);
await db.processedEvents.create({ data: { eventId: event.id } });

Local testing

Use a tunnel tool to expose your local server during development:

# Using ngrok
ngrok http 3000

# Your webhook URL becomes something like:
# https://abc123.ngrok-free.app/api/webhooks

# Using Cloudflare Tunnel (quick tunnel, no account required)
cloudflared tunnel --url http://localhost:3000

# Your webhook URL becomes something like:
# https://<random-subdomain>.trycloudflare.com/api/webhooks

Register the tunnel URL as a webhook endpoint in the dashboard, then trigger test events by creating verification sessions with your stile_sk_ key. In a sandbox org, skip_verification: true produces an instantly verified session that fires real webhooks — see the Testing guide.

Next steps