Webhooks

Webhooks notify your server in real time when events occur in Verifa. Configure a webhook URL in your organization settings to start receiving events.

Event types

For the complete event catalog with payload examples, see the Webhooks Guide and Handling Webhook Events tutorial.

Payload format

Every payload uses the same envelope: event, created_at, and idempotency_key sit at the top level, and all event-specific fields are nested under data. Route on event, then read the resource fields from data (e.g. body.data.session_id).

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
}

The data contents vary by event type — see the event reference below and the Handling webhook events tutorial.

identity.flagged

Fires when an identity is flagged for review. The payload intentionally omits the reviewer email and free-text reason — fetch them from GET /identities/{identity_id} if your subscriber has the right scopes.

1
{
2
  "event": "identity.flagged",
3
  "created_at": "2026-02-01T12:05:00Z",
4
  "data": {
5
    "identity_id": "idn_abc123",
6
    "session_id": "ses_def456",
7
    "has_reason": true,
8
    "is_sandbox": false
9
  }
10
}

consortium.match_found

Fires when consortium matching detects a face match for the same individual across two organizations participating in the Verifa Network. Both involved organizations receive the event.

1
{
2
  "event": "consortium.match_found",
3
  "created_at": "2026-02-01T12:05:00Z",
4
  "data": {
5
    "consortium_id": "cgrp_abc123",
6
    "matched_session_id": "ses_def456",
7
    "primary_session_id": "ses_abc123",
8
    "similarity": 0.94,
9
    "ghost_student_score": 78,
10
    "ghost_student_tier": "high",
11
    "is_sandbox": false
12
  }
13
}

Signature verification

Every webhook request 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 HMAC-SHA256 of f"{t}.{raw_request_body}", signed with your endpoint’s whsec_* secret

Always verify the signature and reject deliveries with a t= timestamp more than 5 minutes from your current clock to prevent replay attacks. See Tutorial: Receiving Webhooks & Validating Signatures for the full reference recipe with end-to-end code samples.

1
const crypto = require("crypto");
2
const TOLERANCE = 300; // 5-minute replay window
3
4
function verifyWebhookSignature(body, header, secret) {
5
  const parts = Object.fromEntries(
6
    (header || "").split(",").map((p) => {
7
      const i = p.indexOf("=");
8
      return i > 0 ? [p.slice(0, i), p.slice(i + 1)] : [p, ""];
9
    })
10
  );
11
  const ts = parseInt(parts.t || "0", 10);
12
  const v1 = parts.v1 || "";
13
  if (!ts || !v1) return false;
14
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > TOLERANCE) return false;
15
16
  const signed = Buffer.concat([Buffer.from(`${ts}.`), body]);
17
  const expected = crypto
18
    .createHmac("sha256", secret)
19
    .update(signed)
20
    .digest("hex");
21
  const a = Buffer.from(expected);
22
  const b = Buffer.from(v1);
23
  return a.length === b.length && crypto.timingSafeEqual(a, b);
24
}
25
26
// In your webhook handler:
27
const isValid = verifyWebhookSignature(
28
  req.rawBody,
29
  req.headers["x-verifa-signature"],
30
  process.env.VERIFA_WEBHOOK_SECRET
31
);

Retry behavior

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Verifa retries the delivery with exponential backoff:

After 5 failed retries, the event is marked as failed. Failed events can be viewed in the dashboard.

Testing webhooks

Use the test endpoint to send a test event to your configured URL:

$
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
}

Best practices

• Respond quickly. Return a 200 status code as soon as you receive the event. Process the event asynchronously.
• Handle duplicates. In rare cases (network issues, retries), you may receive the same event more than once. Use the session_id to deduplicate.
• Verify signatures. Always validate the X-Verifa-Signature header to prevent spoofed events.

Related

• Webhooks Guide — Comprehensive setup guide with code examples in 7 languages
• Errors — Error codes returned by webhook API endpoints
• Sessions — Session events and lifecycle