Webhook Integration Guide
Receive real-time notifications in your system when a verification check completes, without polling the API.
Table of Contents#
1. Overview#
When a verification check finishes, our platform sends an HTTPS POST request to the endpoint you configure. The request body is a JSON payload describing the result. Every request is signed with your webhook secret so you can confirm it came from us and was not altered in transit.Webhooks are sent asynchronously and never block the POST /service/checks call that created the check.
2. Setup in the Admin Console#
1.
Open API Access → Check result webhooks.
3.
Set your HTTPS endpoint URL, for example:
https://your-app.example.com/webhooks/kyc
4.
Click Save and copy the signing secret when it is shown.⚠️ The secret is displayed only once, on first enable or when rotated. Store it securely (e.g. in a secrets manager or environment variable).
5.
(Optional) Click Send test webhook to trigger a webhook.test event and confirm your endpoint works.
3. Delivery Behaviour#
| Item | Behaviour |
|---|
| Trigger | After a successful POST /service/checks (async, non-blocking) |
| Method | POST |
| Body | Raw JSON (UTF-8). Sign-verify this exact string |
| Retries | Up to 3 attempts with short backoff |
| Timeout | 10 seconds |
| Success | Any HTTP 2xx response from your endpoint |
Any non-2xx response, or no response within 10 seconds, is treated as a failed attempt and retried.
| Header | Example | Purpose |
|---|
Content-Type | application/json | JSON body |
X-KYC-Event | check.completed | Event name |
X-KYC-Delivery-Id | UUID | Idempotency / dedupe key |
X-KYC-Signature | sha256=<hex> | HMAC-SHA256 of the raw body using your webhook secret |
User-Agent | KYCSolution-Webhook/1.0 | Identifies the sender |
5. Events#
5.1 check.completed#
Fired when a verification check finishes.{
"id": "9f1e2d3c-4444-4555-8666-777788889999",
"event": "check.completed",
"created_at": "2026-11-01T10:05:01.000Z",
"data": {
"check_id": "check-uuid",
"client_id": "8f3c2a1b-1111-2222-3333-444455556666",
"verification_type": "identity_check",
"outcome": "clear",
"reason": null,
"external_id": "crm-user-10042",
"created_at": "2026-11-01T10:05:00.000Z"
}
}
| Field | Description |
|---|
check_id | Check UUID. Fetch full detail via GET /service/checks?id=<check_id> |
client_id | Client UUID |
verification_type | identity_check | document_verification |
outcome | clear | attention | reject |
reason | Human-readable fail/review reasons (nullable) |
external_id | Your CRM ID supplied at client creation (nullable) |
created_at | Check creation time (ISO-8601) |
| Outcome | Meaning |
|---|
clear | Check passed |
attention | Check needs manual review |
reject | Check failed |
5.2 webhook.test#
Sent manually from the Admin console via Send test webhook. Use it to verify connectivity and signature validation.{
"id": "delivery-uuid",
"event": "webhook.test",
"created_at": "2026-11-01T10:06:00.000Z",
"data": {
"check_id": "00000000-0000-0000-0000-000000000000",
"client_id": "00000000-0000-0000-0000-000000000000",
"verification_type": "test",
"outcome": "test",
"reason": "Manual test webhook from Developers panel",
"external_id": null,
"created_at": "2026-11-01T10:06:00.000Z"
}
}
Test events contain placeholder IDs. Do not try to fetch check details for them.
6. Verifying the Signature#
Signature verification is required. Always verify before processing a payload.1.
Read the raw request body as a string. Do not parse and re-serialize the JSON before verifying; even whitespace changes will break the signature.
2.
Compute HMAC-SHA256(rawBody, webhook_secret) and take the hex digest.
3.
Compare it to the value after sha256= in the X-KYC-Signature header using a constant-time comparison.
4.
(Recommended) Check that created_at is recent, and store X-KYC-Delivery-Id to reject duplicates.
Node.js#
Python#
7. Complete Examples#
Express (Node.js)#
Use express.raw() (or middleware that captures the raw body) so the body is not parsed before verification.Flask (Python)#
8. Go-Live Checklist#
9. Troubleshooting#
| Symptom | Likely cause | Fix |
|---|
| Signature always fails | Body was parsed and re-serialized before verifying | Use the raw body (express.raw(), request.get_data()) |
| Signature always fails | Wrong or outdated secret | Rotate the secret in the Admin console and update your config |
| Signature fails intermittently | Proxy or framework modifying the body | Ensure nothing alters the request body before your handler |
| Repeated deliveries of the same event | Endpoint is slow or returned non-2xx | Respond 200 within 10 seconds; process work in the background |
| Duplicate events processed | No dedupe logic | Store and check X-KYC-Delivery-Id |
| No webhooks arriving | URL is not public HTTPS, or webhooks not enabled | Check the Admin console settings and your firewall/TLS setup |
Need help? Contact support with the X-KYC-Delivery-Id of the affected delivery. Modified at 2026-11-01 17:50:48