KYC Solution API Documentation
    • 📘 Enum Reference
    • Webhook Integration Guide
    • Clients
      • Create Client
        POST
      • Get Clients List
        GET
      • Get Client
        GET
    • Checks
      • Request Verification Session
        POST
      • Get Check Result
        GET
      • Get Checks List
        GET
      • Get Client Latest Check
        GET

    Webhook Integration Guide

    Receive real-time notifications in your system when a verification check completes, without polling the API.

    Table of Contents#

    1.
    Overview
    2.
    Setup in the Admin Console
    3.
    Delivery Behaviour
    4.
    Request Headers
    5.
    Events
    6.
    Verifying the Signature
    7.
    Complete Examples
    8.
    Go-Live Checklist
    9.
    Troubleshooting

    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.
    2.
    Enable 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#

    ItemBehaviour
    TriggerAfter a successful POST /service/checks (async, non-blocking)
    MethodPOST
    BodyRaw JSON (UTF-8). Sign-verify this exact string
    RetriesUp to 3 attempts with short backoff
    Timeout10 seconds
    SuccessAny HTTP 2xx response from your endpoint
    Any non-2xx response, or no response within 10 seconds, is treated as a failed attempt and retried.

    4. Request Headers#

    HeaderExamplePurpose
    Content-Typeapplication/jsonJSON body
    X-KYC-Eventcheck.completedEvent name
    X-KYC-Delivery-IdUUIDIdempotency / dedupe key
    X-KYC-Signaturesha256=<hex>HMAC-SHA256 of the raw body using your webhook secret
    User-AgentKYCSolution-Webhook/1.0Identifies 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"
      }
    }
    data fields
    FieldDescription
    check_idCheck UUID. Fetch full detail via GET /service/checks?id=<check_id>
    client_idClient UUID
    verification_typeidentity_check | document_verification
    outcomeclear | attention | reject
    reasonHuman-readable fail/review reasons (nullable)
    external_idYour CRM ID supplied at client creation (nullable)
    created_atCheck creation time (ISO-8601)
    Outcome values
    OutcomeMeaning
    clearCheck passed
    attentionCheck needs manual review
    rejectCheck 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#

    Endpoint is public HTTPS and returns 2xx quickly (under 10 seconds).
    Signature is verified on every request.
    Handling is idempotent using X-KYC-Delivery-Id.
    Heavy work is done asynchronously after sending the ACK.
    Webhook secret is stored securely (not in source code).
    Secret is rotated via the Admin console if compromised.
    Tested with Send test webhook before go-live.

    9. Troubleshooting#

    SymptomLikely causeFix
    Signature always failsBody was parsed and re-serialized before verifyingUse the raw body (express.raw(), request.get_data())
    Signature always failsWrong or outdated secretRotate the secret in the Admin console and update your config
    Signature fails intermittentlyProxy or framework modifying the bodyEnsure nothing alters the request body before your handler
    Repeated deliveries of the same eventEndpoint is slow or returned non-2xxRespond 200 within 10 seconds; process work in the background
    Duplicate events processedNo dedupe logicStore and check X-KYC-Delivery-Id
    No webhooks arrivingURL is not public HTTPS, or webhooks not enabledCheck 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
    Previous
    📘 Enum Reference
    Next
    Create Client
    Built with