CKYC Bulk Webhook Config Create

Endpoint Overview

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

Description

Creates the account-level webhook URL used for CKYC bulk webhook deliveries. Once configured, Surepass sends webhook notifications for supported state changes on both individual and legal bulk batches.

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>`)
Content-Type	Yes	`application/json`

Request Body

Parameter	Type	Required	Description
webhook_url	String	Yes	Destination URL that will receive CKYC bulk webhook events

Example Request

{
    "webhook_url": "https://hooks.example.com/ckyc-bulk"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response payload
data.webhook_url	String	Newly configured account-level webhook URL
status_code	Integer	HTTP status code
success	Boolean	Whether the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "webhook_url": "https://hooks.example.com/ckyc-bulk"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Failed

Invalid Webhook URL

Already Exists

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

Webhook Delivery Payload

Once a webhook URL is configured, Surepass sends an HTTP POST request to that URL with the following JSON payload:

{
    "client_id": "CLIENT123",
    "new_state": "upload_succeeded",
    "timestamp": "2026-04-13T12:00:00Z"
}

Payload Fields

Field	Type	Description
client_id	String	Your batch identifier from the initialize or file-upload API
new_state	String	The state that triggered the webhook
timestamp	String	UTC ISO-8601 timestamp of the event, without milliseconds

Supported Webhook States

State	Description
awaiting_cersai_response	The batch upload was accepted and Surepass is waiting for the final response from CERSAI
upload_succeeded	The final response was received, parsed, and the batch is ready for status retrieval

No webhook is currently sent for intermediate states such as pending, started, uploaded, uploading, or for failed states.

Heads Up

Shared across bulk flows -- The same configured URL receives events for individual and legal CKYC bulk batches under the account.

Trigger only -- The webhook does not include the detailed CKYC record response. Use the relevant status API after receiving the event.

Create-only endpoint -- To replace an existing URL, first call CKYC Bulk Webhook Config Delete, then create the new one.

Direct 2xx required -- Surepass treats non-2xx webhook responses as failed deliveries.

Code Samples

cURL

Python

Node.js

Related Steps

CKYC Bulk Webhook Config Get -- Fetch the current webhook configuration

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 ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc/v1/bulk/webhook-config' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "webhook_url": "https://hooks.example.com/ckyc-bulk" }'

CKYC Bulk Webhook Config Create

CKYC Bulk Webhook Config Create#

Description#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Webhook Delivery Payload#

Payload Fields#

Supported Webhook States#

Code Samples#

Request

Responses

CKYC Bulk Webhook Config Create

Description

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Webhook Delivery Payload

Payload Fields

Supported Webhook States

Code Samples