Webhooks

What it does

A webhook is a URL we POST to whenever something happens in your Certivant org. Instead of polling our API for changes ("did the verification finish yet?"), you give us a URL and we tell you the moment it does. Webhook events are how you keep your own systems in sync — customer-onboarding flows, AML risk databases, CRM tags, internal compliance dashboards.

Where it lives

KYC → Webhooks in the left sidebar. (KYB events ship to the same webhook endpoints — there's no separate KYB webhook config.)

Setup

const sig = req.headers["x-certivant-signature"];
const expected = hmac("sha256", secret).update(rawBody).digest("hex");
if (!timingSafeEqual(sig, expected)) return 401;

Event types

The full list and JSON payloads are documented under KYC → Developer → Webhook events.

Payload shape

Every event has the same envelope:

{
  "id": "evt_2k3f9a...",
  "type": "kyc.request.approved",
  "createdAt": "2026-05-27T14:30:00Z",
  "organizationId": "org_abc123",
  "data": { /* event-specific payload */ }
}

The data field varies per event type. For example, kyc.request.approved ships:

{
  "request": { "id": "kyr_...", "status": "APPROVED", "type": "INDIVIDUAL", ... },
  "applicant": { "id": "ka_...", "fullName": "Jane Doe", "email": "...", ... },
  "decision": { "by": "auto" | "manual", "reviewerId": "user_..." | null, "note": "..." | null },
  "policy": {
    "id": "pol_..." | null,
    "name": "default-kyc-policy",
    "version": 3 | null,
    "isDefault": true,
    "decision": "approve" | "reject" | "escalate" | "live_verification",
    "rulesFired": ["tier1-disqualified", "approve-by-score"],
    "reason": "High-risk country",
    "liveVerificationRequired": true
  }
}

The policy block (on kyc.request.approved / rejected / escalated) tells you which risk policy decided the request and which rules fired. isDefault: true means Certivant's default policy ran (id/version are your organization's default-policy row, or null when it hasn't been created yet); a custom policy reports its stored id, name, and version. rulesFired lists the rule ids that matched, in evaluation order — branch your downstream automation on these. reason is the winning rule's reason when it set one. decision: "live_verification" (with liveVerificationRequired: true, on kyc.request.escalated) means the policy wants a live ID verification before a final decision — the request waits in manual review until the call decides. See Design a risk policy.

If you operate in partner mode (one org serving many end customers), every event envelope also carries subTenantName and subTenantExternalId — the tags set on the request when it was created via the API — so your handler can route the result to the right end customer. See the developer webhook reference for the exact field placement.

Retries

If your endpoint returns non-2xx (or times out), we retry with exponential backoff:

attempt 1: immediately
attempt 2: 30 seconds later
attempt 3: 5 minutes later
attempt 4: 30 minutes later
attempt 5: 2 hours later
attempt 6: 6 hours later
attempt 7: 24 hours later

After 7 failed attempts we mark the event as permanently_failed and stop retrying. Failed events appear in the webhooks dashboard with their last error; you can manually re-fire any of them with Retry.

Multiple endpoints

You can register multiple endpoints (e.g., one for your CRM, one for your AML data lake). Each can subscribe to a different set of event types. Per-endpoint signing secrets — rotating one doesn't break the others.

Per-form webhooks

The org-wide webhook fires for every relevant event. Public forms can ALSO have a per-form webhook URL under their settings — useful when one form feeds a separate system. Per-form webhooks run in addition to the org-wide ones.

The KYC → Webhooks page now lists both in one place: your organization webhook URL at the top, and a row for each form's webhook URL below it — so you can see every place events are delivered without hunting through individual form settings.

The webhooks dashboard

KYC → Webhooks lists every endpoint with:

• Endpoint URL + friendly name.
• Status — active / paused / failing.
• Last delivery — when the most recent event was POSTed.
• Success rate — % of attempts that returned 2xx in the last 7 days.
• Recent deliveries — table of recent events with status code, latency, and response body.

Pause an endpoint to stop deliveries without losing the config.

Troubleshooting

My endpoint is getting hammered

Endpoints are called once per event, but a busy org might fire dozens per minute. Make your endpoint async — accept the POST, ack 2xx immediately, process the payload off the request lifecycle. If you need to slow us down, set the per-endpoint Max concurrent deliveries option.

Signature verification keeps failing

Three common causes:

1. Parsing the body before verifying the signature. Use the raw bytes. Express + body-parser users: set bodyParser.raw({ type: 'application/json' }) for the webhook route specifically.
2. Wrong secret. Rotate and re-paste.
3. Stripping or transforming the body in a middleware (gzip, BOM, encoding). The signature is over the exact bytes we sent.

Events look duplicated

Retries on slow responses. Key off event.id for idempotency.

Order of events matters but I'm seeing them out of order

We don't guarantee strict ordering across event types. For per-applicant ordering use the createdAt field on the event; the order within a single applicant's lifecycle is monotonic.

Related

• Audit log — every webhook fire is also logged here.
• Developer (API keys) — if you want to pull state via REST instead of receiving pushes.
• Forms — preview & publish — per-form webhooks.