Webhook events triggered by a participant status update.
Platforms leveraging Zero Hash’s customer verification product should subscribe to webhooks to know if participants have been approved or rejected. This webhook can also be used by all platforms to understand if participants’ statuses have changed (i.e. if the participant has been locked or disabled).
Request an overview of reject reasons during implementation
If you are a signed or prospective Zero Hash Platform subscribing to this webhook, you can request the complete list of reject reasons by contacting your Relationship Manager or by emailing [email protected].
Once a platform is configured to receive participant status webhooks, we will share real time events that include a JSON object containing the following fields:
Parameters
| Parameter | Description | Type |
|---|---|---|
| participant_code | The Zero Hash identifier for the new customer. Note: this value is key to enable you to submit trades and check account balances for this customer. | string |
| participant_status | The status of the participant, which dictates whether they can trade or not. e.g. submitted, pending_approval, approved, rejected, locked, disabled, divested, closed. | string |
| reason_code | If applicable, the reason the participant is in a status of locked, disabled, closed, or divested; e.g. compliance_issue, user_request. On rejection, this is set to reject_reasons[0]. | string |
| timestamp | The UNIX timestamp (in milliseconds) representing when the status was changed. | number |
| reject_reasons | If applicable, the reason(s) that a participant could have failed KYC verification. This is currently only applicable to participant rejections. | string[] |
| kyc_attempts | Number of attempts the participant has been rejected. By default there is a max amount of 3 retries allowed. If the participant is approved, this counter resets to 0. | number |
Payloads
Participant submitted
{
"participant_code": "ABC123",
"participant_status": "submitted",
"timestamp": 1670958435349
}
Participant approved
{
"participant_code": "ABC123",
"participant_status": "approved",
"timestamp": 1670958435349,
"kyc_attempts": 0
}
Verification failed
{
"participant_code": "ABC123",
"participant_status": "rejected",
"reason_code": "kyc.rejected",
"timestamp": 1708489569494,
"reject_reasons": [
"kyc.idv.name_not_extracted",
"kyc.pii.national_id_not_present"
],
"kyc_attempts": 1
}
Participant status change
{
"participant_code": "ABC123",
"participant_status": "locked",
"reason_code": "compliance_issue",
"timestamp": 1670958435349
}