CKYC Bulk Webhook Test

Endpoint Overview

POST /api/v1/ckyc/v1/bulk/webhook-test

Description

Dispatches a one-off randomized test payload to the account's currently configured CKYC bulk webhook_url and returns the outcome synchronously. Use it to verify that your receiver is reachable, responds with a 2xx, and handles the event payload shape before any real CKYC batch fires.

Every call records a row in Surepass's webhook outbox (with document_type="TestWebhook") so support can correlate the attempt if you need help debugging.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Environment URLs:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer JWT token (`Bearer <JWT>`)

Request Body

This endpoint does not require any request body. The account email is derived from the authenticated user context, and the target URL is read from the account's stored webhook configuration.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response payload
data.delivery_id	String	Unique id of the recorded delivery attempt (useful when contacting support)
data.status	String	Final delivery status: `delivered`, `failed`, `timed_out`, or `unknown`
data.status_code	Integer \| Null	HTTP status code returned by your receiver (null for timeouts/network errors)
data.latency_ms	Integer \| Null	Round-trip latency in milliseconds
data.error	String \| Null	Error detail when `status` is not `delivered`
data.webhook_url	String	The URL the payload was dispatched to
data.payload	Object	The randomized payload that was sent to the receiver
status_code	Integer	HTTP status code of this API call
success	Boolean	Whether this API call itself succeeded
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "delivery_id": "69e74d520c297482d64990a4",
        "status": "delivered",
        "status_code": 200,
        "latency_ms": 4,
        "error": null,
        "webhook_url": "https://hooks.example.com/ckyc-bulk",
        "payload": {
            "client_id": "test_82ce88a428f5",
            "new_state": "awaiting_cersai_response",
            "timestamp": "2026-04-21T10:11:30Z",
            "test": true
        }
    },
    "status_code": 200,
    "message": "Success",
    "message_code": "success",
    "success": true,
    "errors": null
}

Non-Delivered Outcomes

A non-delivered outcome is not an API error -- this endpoint still returns status_code: 200 and success: true. The delivery result is communicated via data.status.

Receiver Returned Non-2xx

Receiver Timed Out

{
    "data": {
        "delivery_id": "69e74d520c297482d64990a5",
        "status": "failed",
        "status_code": 500,
        "latency_ms": 17,
        "error": "webhook responded with status 500",
        "webhook_url": "https://hooks.example.com/ckyc-bulk",
        "payload": {
            "client_id": "test_7fa31bd69c40",
            "new_state": "upload_succeeded",
            "timestamp": "2026-04-21T10:12:04Z",
            "test": true
        }
    },
    "status_code": 200,
    "message": "Success",
    "message_code": "success",
    "success": true,
    "errors": null
}

Possible Error Responses

Authentication Failed

Account Not Found

No Webhook Configured

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Unauthorized",
    "message_code": "auth_failed"
}

The JWT token is missing, expired, or invalid.

Test Payload

Every call generates a fresh randomized payload that is sent to your receiver:

{
    "client_id": "test_82ce88a428f5",
    "new_state": "awaiting_cersai_response",
    "timestamp": "2026-04-21T10:11:30Z",
    "test": true
}

Payload Fields

Field	Type	Description
client_id	String	Synthetic id prefixed with `test_` and a random hex suffix -- never matches a real CKYC batch
new_state	String	One of `awaiting_cersai_response` or `upload_succeeded`, chosen at random
timestamp	String	UTC ISO-8601 timestamp of the test, without milliseconds
test	Boolean	Always `true` so your receiver can distinguish a test from a real event

The payload shape mirrors the real CKYC bulk webhook event documented in CKYC Bulk Webhook Config Create, with an additional test: true flag. Your receiver should tolerate the extra key.

Heads Up

Real HTTP dispatch -- The test hits your live webhook_url with the same HTTP client, timeouts, and 2xx-means-delivered semantics as production events. Make sure the URL is one you actually want pinged.

Synthetic client_id -- The test_ prefix means your receiver must not attempt to look this id up in any internal system.

Shared with the real queue -- The attempt is written to the same webhook outbox Surepass uses for production deliveries, so the result is visible to support.

Rate-friendly but not unlimited -- Use it to validate setup and during incident debugging, not as a health probe.

Code Samples

cURL

Python

Node.js

Related Steps

CKYC Bulk Webhook Config Get -- Check which webhook URL the test will dispatch to

CKYC Bulk Webhook Config Create -- Configure the webhook URL and view the real event payload schema

CKYC Bulk Webhook Config Delete -- Remove the configured webhook URL

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

{ "data": { "delivery_id": "69e74d520c297482d64990a4", "status": "delivered", "status_code": 200, "latency_ms": 4, "error": null, "webhook_url": "https://hooks.example.com/ckyc-bulk", "payload": { "client_id": "test_82ce88a428f5", "new_state": "awaiting_cersai_response", "timestamp": "2026-04-21T10:11:30Z", "test": true } }, "status_code": 200, "message": "Success", "message_code": "success", "success": true, "errors": null }

CKYC Bulk Webhook Test

CKYC Bulk Webhook Test#

Description#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Non-Delivered Outcomes#

Possible Error Responses#

Test Payload#

Payload Fields#

Code Samples#

Request

Responses

CKYC Bulk Webhook Test

Description

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Non-Delivered Outcomes

Possible Error Responses

Test Payload

Payload Fields

Code Samples