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

Payload format

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

Signature verification

Every webhook request includes an X-Verifa-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

Always verify the signature before processing the event.

1
const crypto = require("crypto");
2
3
function verifyWebhookSignature(body, signature, secret) {
4
  const expected = crypto
5
    .createHmac("sha256", secret)
6
    .update(body)
7
    .digest("hex");
8
  return crypto.timingSafeEqual(
9
    Buffer.from(signature),
10
    Buffer.from(expected)
11
  );
12
}
13
14
// In your webhook handler:
15
const isValid = verifyWebhookSignature(
16
  req.rawBody,
17
  req.headers["x-verifa-signature"],
18
  process.env.VERIFA_WEBHOOK_SECRET
19
);

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