Webhook API

PixDynamics sends webhook notifications to inform your system of important VKYC session status changes — session started, verification completed, agent or auditor rejections with remarks, CBS outcomes, and more.

POSThttps://<your-domain>/your-webhook-endpoint

Endpoint requirements

Requirement	Description
HTTPS URL	Must be publicly accessible over HTTPS.
HTTP method	POST
Content-Type	application/json
Timeout	Your server must respond within 5 seconds.
Expected acknowledgment	HTTP 200 OK to confirm receipt.

:::note Custom authentication If your webhook endpoint requires an API key or custom authentication, we can integrate it and pass the required headers on every webhook call. :::

Common webhook structure

{
  "event": "<event_name>",
  "timestamp": "2025-07-11T10:00:00Z",
  "trace_id": "<PixDynamics unique reference ID>",
  "VKYC_ref_id": "<reference ID>",
  "customer_ref": "REF20250711-001",
  "status": "<Status of the application>",
  "data": {
    "remark": ""
  }
}

Parameter specification

Parameter	Type	Mandatory	Description
event	string	Yes	Webhook event name, e.g. vcip.requested, vcip.started.
timestamp	string	Yes	ISO 8601 UTC timestamp, e.g. 2025-07-11T10:00:00Z.
trace_id	string	Yes	PixDynamics unique reference for the notification — useful for debugging.
VKYC_ref_id	string	Yes	Internal PixDynamics session / customer ID.
customer_ref	string	Yes	Client-provided customer reference ID.
status	string	Varies	Status tag: requested, onqueue, on_call, verified, and so on.
data	object	Yes	Event-specific payload — see below.

Inside data

Field	Type	Mandatory	Description
agent_id	string	Conditional	ID of the agent handling the session — started, allotted.
old_agent	string	Conditional	Previous agent — used in reassigned.
new_agent	string	Conditional	Newly assigned agent — used in reassigned.
verified_by	string	Conditional	Agent ID / email that verified — verification.agent.
verified_at	string	Conditional	Verification timestamp — verification.agent.
remarks	string	Optional	Remarks from the agent, checker or auditor.
rejected_by	string	Conditional	Agent ID / email that rejected — verification.agent.
rejected_at	string	Conditional	Rejection timestamp — verification.agent.
rejection_reason	string	Conditional	Reason code, e.g. id_mismatch — agent / auditor rejection.
rejection_remark	string	Optional	Explanation for the rejection — agent / auditor rejection.
checked_by	string	Conditional	Checker ID / email — verification.checker.
status	string	Conditional	approved / rejected — verification.checker.
audited_by	string	Conditional	Auditor ID / email — verification.auditor.
audited_at	string	Conditional	Audit timestamp — verification.auditor.
extended_by	integer	Optional	Time extended in queue — queue_extend.
reason	string	Conditional	Reason for a call drop, e.g. inactivity, network_issue — call_dropped.

Webhook event types

Event name	Status	Trigger condition / description
vcip.requested	Requested	The customer clicks "Start KYC" — that is, opens the session link.
vcip.queued	Onqueue	The customer is added to the global queue.
vcip.queue_extend	QueueExtend	The customer chooses to extend the queue wait time.
vcip.call_dropped	Call Dropped	The session ends unexpectedly — inactivity, app closure, etc.
vcip.allotted	Allotted	The system assigns the customer to an agent.
vcip.reassigned	ReAssign	The customer is reassigned to another agent.
vcip.started	On Call	The live video call between customer and agent starts.
vcip.call_scheduled	Call Scheduled	The call is scheduled for a later date and time.
verification.agent	Verified / Rejected	The agent verifies or rejects the customer's application.
verification.checker	Approved / Declined	The checker approves or rejects the application.
verification.auditor	Approved / Declined	The auditor completes the final review.
verification.dms_upload_status	DMS Upload Status	Documents are uploaded to the DMS.
cbs.cif_success	Approved	The CIF creation API was called successfully.
cbs.account_success	Approved	The account creation API was called successfully.
cbs.remove_stop_success	Approved	The remove-stop API was triggered successfully.
cbs.photo_signature_success	Approved	Signature and photo upload completed successfully.

Event-specific payloads

vcip.requested

{
  "event": "vcip.requested",
  "timestamp": "2025-07-11T10:00:00Z",
  "trace_id": "ed126fa3-9821-455a-abc1-b93190c1349e",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "requested",
  "data": {
    "remark": ""
  }
}

vcip.started

{
  "event": "vcip.started",
  "timestamp": "2025-07-11T10:01:00Z",
  "trace_id": "8d22fa7c-9df5-4e88-82b4-717ebcd56a45",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "on_call",
  "data": {
    "agent_id": "AGT001"
  }
}

verification.agent — verified

{
  "event": "verification.agent",
  "timestamp": "2025-07-11T10:10:00Z",
  "trace_id": "0bbab84e-23b3-4ff9-9e2b-c9f3c3de13fa",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "verified",
  "data": {
    "verified_by": "AGT001",
    "verified_at": "2025-07-11T10:10:00Z",
    "remarks": "Customer verified successfully."
  }
}

verification.agent — rejected

{
  "event": "verification.agent",
  "timestamp": "2025-07-11T10:07:00Z",
  "trace_id": "54a33f45-c394-4b1d-8022-7a4b0cbe63a9",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "rejected",
  "data": {
    "rejected_by": "AGT001",
    "rejected_at": "2025-07-11T10:07:00Z",
    "rejection_reason": "id_mismatch",
    "rejection_remark": "PAN name mismatch with Aadhaar"
  }
}

verification.checker

{
  "event": "verification.checker",
  "timestamp": "2025-07-11T10:15:00Z",
  "trace_id": "a2197c76-0b0b-4e1d-8a18-2991fef0aabf",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "declined",
  "data": {
    "checked_by": "CKR001",
    "remarks": ""
  }
}

verification.auditor

{
  "event": "verification.auditor",
  "timestamp": "2025-07-11T10:20:00Z",
  "trace_id": "fcb8a4bc-efb1-41f7-aad5-c1f33c7ed101",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "declined",
  "data": {
    "audited_by": "AUD001",
    "audited_at": "2025-07-11T10:20:00Z",
    "rejection_reason": "blurred_video",
    "rejection_remark": "Unable to validate due to poor video quality"
  }
}

vcip.call_dropped

{
  "event": "vcip.call_dropped",
  "timestamp": "2025-07-11T10:20:00Z",
  "trace_id": "fcb8a4bc-efb1-41f7-aad5-c1f33c7ed101",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "call_dropped",
  "data": {
    "remark": ""
  }
}

vcip.call_scheduled

{
  "event": "vcip.call_scheduled",
  "timestamp": "2025-07-11T10:20:00Z",
  "trace_id": "fcb8a4bc-efb1-41f7-aad5-c1f33c7ed101",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "call_scheduled",
  "data": {
    "schedule_date": "DD-MM-YYYY",
    "schedule_time": "HH:MM AM/PM",
    "link": "<call_link>"
  }
}

verification.dms_upload_status

{
  "event": "verification.dms_upload_status",
  "timestamp": "2025-07-11T10:20:00Z",
  "trace_id": "fcb8a4bc-efb1-41f7-aad5-c1f33c7ed101",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "dms_upload_status",
  "data": [
    {
      "documentType": "",
      "documentName": "",
      "dmsDocId": ""
    },
    {
      "documentType": "",
      "documentName": "",
      "dmsDocId": ""
    }
  ]
}

cbs.cif_success

{
  "event": "cbs.cif_success",
  "timestamp": "2025-07-11T11:15:00Z",
  "trace_id": "0bbab84e-23b3-4ff9-9e2b-c9f3c3de13fa",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "success",
  "data": {
    "cif_number": "987654321",
    "account_number": "",
    "remark": "Customer CIF create successful."
  }
}

cbs.account_success

{
  "event": "cbs.account_success",
  "timestamp": "2025-07-11T11:20:00Z",
  "trace_id": "0bbab84e-23b3-4ff9-9e2b-c9f3c3de13fa",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "success",
  "data": {
    "cif_number": "987654321",
    "account_number": "12345678901",
    "remark": "Customer account create successful."
  }
}

cbs.remove_stop_success

{
  "event": "cbs.remove_stop_success",
  "timestamp": "2025-07-11T11:30:00Z",
  "trace_id": "0bbab84e-23b3-4ff9-9e2b-c9f3c3de13fa",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "success",
  "data": {
    "cif_number": "987654321",
    "account_number": "12345678901",
    "remark": "RemoveStop successful."
  }
}

cbs.photo_signature_success

{
  "event": "cbs.photo_signature_success",
  "timestamp": "2025-07-11T11:25:00Z",
  "trace_id": "0bbab84e-23b3-4ff9-9e2b-c9f3c3de13fa",
  "VKYC_ref_id": "VX123456",
  "customer_ref": "REF20250711-001",
  "status": "success",
  "data": {
    "cif_number": "987654321",
    "account_number": "12345678901",
    "remark": "Signature upload successful."
  }
}

Acknowledging a webhook

POST/your-webhook-endpoint

POST /your-webhook-endpoint HTTP/1.1
Host: your-domain.com
Content-Type: application/json

{
"event": "vcip.started",
"timestamp": "2025-07-11T10:01:00Z",
"trace_id": "8d22fa7c-9df5-4e88-82b4-717ebcd56a45",
"VKYC_ref_id": "VX123456",
"customer_ref": "REF20250711-001",
"status": "on_call",
"data": { "agent_id": "AGT001" }
}

200

HTTP/1.1 200 OK