Webhook events related to participants.
Webhooks are a powerful tool for receiving real-time notifications about your participants and data updates from Zero Hash's systems. By configuring webhooks, you can streamline your workflow and stay informed about events related to your participants.
Configuring Webhooks
- Contact Zero Hash: Reach out to Zero Hash directly to initiate the webhook configuration process. You can do this via the platform Slack channel or by contacting your Zero Hash relationship manager.
- Provide URLs: Provide the URLs for your production (Prod) and certification (Cert) webhooks to Zero Hash. These URLs will be where Zero Hash sends the webhook payloads.
- Wait for Configuration: Zero Hash will configure the webhooks within 2 business days of receiving the URLs. Once configured, you will start receiving webhook notifications according to your participant events.
Webhook URLs
Ensure that you provide separate URLs for production and certification environments. This helps in distinguishing between live and test data, allowing you to safely test webhook integrations without affecting your production environment.
Handling Webhook Payloads
Upon receiving webhook payloads, your system should be capable of processing and interpreting the data. Parse the payload according to the provided documentation and handle events appropriately based on your application logic.
Retry Policy
- Upon failure to send a webhook notification, Zero Hash will up to 5 more attempts to POST the notification.
- Each retry will have a 250 millisecond delay between each attempt to your webhook listener.
Participant Status Definitions
| Status | Definition |
|---|---|
| submitted | Successfully submitted to <POST /participants/customers/new> and given a participant code, but has not yet been approved to transact. |
| pending_approval | Participant requires manual review by Zero Hash before moving to an approved or rejected status. |
| approved | Participant code and relationships created and the participant passes necessary approvals to transact. |
| rejected | Participant who was rejected from becoming an active user; most often due to customer verification declines. |
| locked | Investigative state for the Zero Hash compliance team. |
| pending_unlock | Investigations conclude the participant may remain active on Zero Hash. Only available via GET /participants, and not via webhook. |
| pending_disable | Investigations conclude the participant should be indefinitely banned from Zero Hash. Only available via GET /participants, and not via webhook. |
| disabled | Indefinitely banned from Zero Hash, but balances may exist in the participant account. Zero Hash settlement team will divest existing balances. |
| divested | Indefinitely banned from Zero Hash and participant balances were moved back to the platform float. |
| closed | Indefinitely banned from Zero Hash and no balances remained at the time of ban |
Participant Reason Codes and Request Availability
| Reason Code | Definition | Request Availability |
|---|---|---|
| compliance_issue | locked | None |
| compliance_issue | pending_disable | None |
| compliance_issue | disabled | None |
| compliance_issue | closed | None |
| compliance_issue | divested | None |
| user_request | locked | Closing only (sell/withdraw) |
| user_request | pending_disable | Closing only (sell/withdraw) |
| user_request | disabled | None |
| user_request | closed | None |
| user_request | divested | None |
| risk_cleared | pending_unlock | None - the cleared risk still needs to be approved |
| risk_cleared | approved | All |