Webhooks Guide

Webhooks deliver real-time event notifications to your server when things happen in Verifa — sessions complete, screening finds matches, identities update, and more. This guide covers setup, security, event filtering, and best practices.

Quick setup

1. Create a webhook endpoint

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://your-app.com/webhooks/verifa",
>
    "enabled_events": ["session.approved", "session.declined", "session.requires-review"],
>
    "description": "Production webhook"
>
  }'

1
{
2
  "id": "webhook_abc123",
3
  "url": "https://your-app.com/webhooks/verifa",
4
  "secret": "whsec_abc123def456...",
5
  "enabled_events": ["session.approved", "session.declined", "session.requires-review"],
6
  "enabled": true,
7
  "created_at": "2026-02-01T12:00:00Z"
8
}

Store the secret securely — you need it to verify webhook signatures. The whsec_* value is shown once at creation and again only when you rotate it. You cannot retrieve it later. Each endpoint has its own per-endpoint secret, so rotating one endpoint never affects another.

2. Handle events

The X-Verifa-Signature header uses the Stripe-style format t=<unix_ts>,v1=<hex_hmac>. The HMAC-SHA256 covers f"{t}.{raw_body}" and receivers should reject any delivery whose t= is more than 5 minutes from current time (replay protection). See the Tutorial: Receiving Webhooks & Validating Signatures for full code samples and a reference recipe.

1
const express = require("express");
2
const crypto = require("crypto");
3
4
const app = express();
5
const TOLERANCE = 300; // 5-minute replay window
6
7
function verify(rawBody, header, secret) {
8
  const parts = Object.fromEntries(
9
    (header || "").split(",").map((p) => {
10
      const i = p.indexOf("=");
11
      return i > 0 ? [p.slice(0, i), p.slice(i + 1)] : [p, ""];
12
    })
13
  );
14
  const ts = parseInt(parts.t || "0", 10);
15
  const v1 = parts.v1 || "";
16
  if (!ts || !v1) return false;
17
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > TOLERANCE) return false;
18
19
  const signed = Buffer.concat([Buffer.from(`${ts}.`), rawBody]);
20
  const expected = crypto
21
    .createHmac("sha256", secret)
22
    .update(signed)
23
    .digest("hex");
24
  const a = Buffer.from(expected);
25
  const b = Buffer.from(v1);
26
  return a.length === b.length && crypto.timingSafeEqual(a, b);
27
}
28
29
app.post("/webhooks/verifa", express.raw({ type: "application/json" }), (req, res) => {
30
  const signature = req.headers["x-verifa-signature"];
31
  if (!verify(req.body, signature, process.env.VERIFA_WEBHOOK_SECRET)) {
32
    return res.status(401).send("Invalid or expired signature");
33
  }
34
35
  // Process event
36
  const event = JSON.parse(req.body);
37
  console.log(`Received ${event.event} for session ${event.data.session_id}`);
38
39
  // Respond immediately — process asynchronously
40
  res.status(200).send("OK");
41
  processEvent(event);
42
});

3. Test it

Send a test event to verify your endpoint is working:

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123/test \
>
  -H "X-API-Key: vk_live_your_key_here"

1
{
2
  "success": true,
3
  "http_status": 200,
4
  "url": "https://your-app.com/webhooks/verifa"
5
}

Event catalog

Session events

Screening events

Identity events

Consortium events

Case events

Document events

Quality assurance events

Event filtering

Subscribe to specific events or use "*" to receive all events:

$
curl -X PATCH https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "enabled_events": ["session.approved", "session.declined", "screening.monitoring.new_hits"]
>
  }'

Payload format

All webhook payloads use the same envelope: event, created_at, and idempotency_key sit at the top level, and every event-specific field is nested under data.

1
{
2
  "event": "session.approved",
3
  "created_at": "2026-02-01T12:05:00Z",
4
  "idempotency_key": "idk_a1b2c3d4e5f6...",
5
  "data": {
6
    "session_id": "session_abc123",
7
    "external_ref": "user_abc123",
8
    "status": "approved",
9
    "is_sandbox": false
10
  }
11
}

Route on the top-level event, then read resource fields from data (e.g. body.data.session_id). The data contents vary by event type — session events include session_id, external_ref, and status; identity events include identity_id and the changed fields. See Handling webhook events for the full per-event field reference.

Signature verification

Every webhook includes an X-Verifa-Signature header in the Stripe-style format t=<unix_ts>,v1=<hex_hmac>:

• t — Unix timestamp the signature was generated at
• v1 — hex-encoded HMAC-SHA256 of f"{t}.{raw_request_body}", signed with your endpoint’s whsec_* secret

Always verify signatures to prevent spoofed events. Use the raw request body bytes (not parsed JSON) for verification, use a constant-time comparison function for the v1 value, and reject deliveries whose t= is more than 5 minutes from your current clock to prevent replay attacks. See the Tutorial: Receiving Webhooks & Validating Signatures for the full reference recipe and language-specific examples.

Replay protection

Receivers should layer the following defenses:

1. Verify the signature using the t=,v1= recipe above — reject anything that doesn’t validate.
2. Reject stale timestamps. If abs(now - t) > 300, drop the delivery even if the HMAC checks out. This is the same 5-minute window enforced by every Verifa client.
3. Dedupe on idempotency_key. Verifa retries failed deliveries, and the same event may arrive more than once with the same idempotency_key in the payload body. Maintain a short-lived cache (Redis, DB row) keyed on idempotency_key to skip duplicates rather than hashing payloads.

Retry behavior

If your endpoint returns a non-2xx status or doesn’t respond within 30 seconds, Verifa retries with exponential backoff:

After 5 failed retries, the delivery is marked as failed.

Circuit breaker

If an endpoint accumulates 10 consecutive failed deliveries (all retries exhausted), Verifa automatically disables the endpoint and sends an email notification to your organization’s admins. Re-enable it in the dashboard or via API after fixing the issue.

Troubleshooting delivery failures

Deliveries are blocked by a firewall, WAF, or bot protection

This is the single most common reason a brand-new webhook endpoint never receives events. Verifa delivers webhooks as server-to-server POST requests — there is no browser, no JavaScript engine, and no human behind them. Bot-protection products are tuned to flag exactly that traffic shape, so they often challenge or block the request before it ever reaches your application.

The tell-tale sign is a delivery that fails with HTTP 403 and a response body containing an interstitial challenge page (for example, Cloudflare’s "Just a moment..." page) rather than your own API’s response. Check the delivery’s error in Developers → Webhooks → delivery history.

Common culprits and fixes:

• Cloudflare — Bot Fight Mode, Super Bot Fight Mode, Managed Challenge, or Browser Integrity Check. Add a WAF custom rule that skips these for your webhook path (e.g. URI Path equals /webhooks/verifa), or set a configuration-rule exception for that route.
• AWS WAF / Akamai / Imperva / Cloudfront — add an allow rule for the webhook path, or for requests carrying the X-Verifa-Signature header.
• Self-managed firewalls / IP allowlists — allow inbound traffic to your webhook path from Verifa’s egress.

You can scope the exception narrowly by matching on either of these, both present on every delivery:

• the X-Verifa-Signature header — only HMAC-signed Verifa traffic bypasses the challenge; or
• our User-Agent, which always starts with Verifa-Webhooks/ (e.g. Verifa-Webhooks/1.0 (+https://docs.withverifa.com/webhooks)).

For example, in Cloudflare a custom rule of Skip → when User-Agent starts with Verifa-Webhooks/ is enough to let deliveries through.

Other things to check

• TLS errors — confirm your endpoint serves a valid, non-expired certificate for the exact hostname in the URL, and that it presents the full chain. Verifa validates certificates and will not deliver to a host that fails the handshake.
• Timeouts — your handler must return a response within 30 seconds. Return 200 immediately and process asynchronously (see Best practices).
• Wrong status code — only 2xx counts as success. A 3xx redirect is treated as a failure; point the endpoint URL directly at its final location.
• Reachability — the URL must be publicly resolvable. localhost, private IP ranges, and internal-only hostnames are rejected. Use a tunnel (e.g. ngrok) for local development.

Managing endpoints

Rotate the signing secret

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123/rotate-secret \
>
  -H "X-API-Key: vk_live_your_key_here"

Returns the new whsec_* secret in the response body. This is the only other time the secret is shown — store it immediately. The previous secret is invalidated as soon as rotation completes, so deploy the new value to your server before or immediately after rotating. Rotating one endpoint never affects another endpoint’s secret.

Clone an endpoint

Duplicate an endpoint with a new secret (useful for migration):

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123/clone \
>
  -H "X-API-Key: vk_live_your_key_here"

View delivery history

$
curl https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123/deliveries \
>
  -H "X-API-Key: vk_live_your_key_here"

Retry a failed delivery

$
curl -X POST https://api.withverifa.com/api/v1/webhooks/deliveries/webhookdlv_abc123/retry \
>
  -H "X-API-Key: vk_live_your_key_here"

Key inflection

Control the casing of payload keys per endpoint:

$
curl -X PATCH https://api.withverifa.com/api/v1/webhooks/endpoints/webhook_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "key_inflection": "camel"
>
  }'

Options: snake (default), camel, kebab.

Best practices

• Respond quickly. Return 200 immediately and process the event asynchronously. If your handler takes too long, the delivery may time out and trigger unnecessary retries.

• Handle duplicates. Use the idempotency_key field on the payload body to deduplicate — the same key arrives on every retry of the same delivery. In rare cases (network issues, retries), you may receive the same event more than once.

• Verify signatures and timestamps. Parse t= and v1= from the X-Verifa-Signature header, recompute the HMAC over f"{t}.{raw_body}", and reject any delivery whose t= is more than 5 minutes from now. Never process unverified events.

• Exempt from CSRF. If your framework has CSRF protection, exempt your webhook endpoint path.

• Use specific events. Subscribe only to the events you need rather than "*". This reduces noise and makes your handler simpler.

• Monitor delivery health. Check the delivery history in the dashboard regularly. If you see frequent failures, investigate timeouts or errors on your endpoint.

Related

• Webhooks — Quick reference for event types and payload format
• Sessions — Session events and lifecycle
• Screening & Reports — Screening event details
• Errors — Error codes returned by webhook API endpoints