Basic information about how our webhooks work
Webhooks are a powerful tool for receiving real-time notifications about your payment updates from zerohash's systems. By configuring webhooks, you can streamline your workflow and stay informed about events related to your payments.
One URL for all webhook eventsAs a platform, you will receive all webhook notifications under one destination URL that you provide for each environment (CERT and PROD).
Configuring webhooks
- Contact zerohash: Reach out to zerohash directly to initiate the webhook configuration process. You can do this via the platform Slack channel or by contacting your zerohash relationship manager.
- Provide URLs: Provide the URLs for your production (Prod) and certification (Cert) webhooks to zerohash. These URLs will be where zerohash sends the webhook payloads.
- Wait for Configuration: zerohash 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 make up to 4 additional fast retry attempts.
- Each fast retry is delayed by 250 milliseconds before contacting your webhook listener.
- If all fast retries are exhausted, the notification is enqueued and re-attempted 3 more times using an exponential backoff strategy.
- If all retries with exponential backoff are exhausted, the notification is dropped. The client must then perform a manual state recovery upon resuming operation.
Sequencing and order
The client should interpret event sequence not by the order of each webhook message, but instead by the timestamp field.
Order of webhooksWhen sorting webhooks to determine the sequence by which they happened, use the
timestampfield. This field determines when the event associated with the webhook took place. Conversely, you should not rely on the order by which you receive the webhook to determine the sequence.
Headers
We use headers to tell you important information about the notification we send. You can use that to tell different payloads, check for idempotency and important Webhook Security information.
| Header Key | Type | Description |
|---|---|---|
x-zh-hook-notification-id | string | Notification ID, used for idempotency check |
x-zh-hook-payload-type | string | Payload type. Use it to tell from different format |
Payload type
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.
We support the following values for payload-type:
payload-type | Purpose | Examples and more details |
|---|---|---|
participant_status_changed | Fires whenever a participant's status changes: approved, rejected, locked, and everything in between | Link |
participant_updated | Fires whenever a participant's onboarding or profile data is updated, independent of status | Link |
payment_status_changed | Fires whenever a fiat payment moves to a new state, from submission through settlement or failure | Link |
deposit_fund_complete | Fires once a funding deposit into a platform's account successfully completes | Link |
external_account_status_changed | Fires whenever a linked external bank account changes status: verified, invalid, or closed | Link |
asset_mover_update | Fires whenever a tracked asset's price crosses a configured movement threshold | Link |
account_balance.changed | Fires whenever an account's balance changes, for any reason | Link |
trade.status_changed | Fires whenever a trade moves through its lifecycle, from execution to settlement | Link |
deposit.status_changed | Fires whenever a blockchain deposit's status changes, from pending through confirmed or failed | Link |
auth_deposit.status_changed | Fires on auth-specific deposit status changes | Link |
withdrawal.status_changed | Fires whenever a withdrawal's status changes, from submission through completion or failure | Link |
auth_withdrawal.status_changed | Fires on auth-specific withdrawal status changes | Link |
virtual_account.status_changed | Fires whenever a virtual account's status changes: active, closed, blocked, failed, or suspended | Link |
virtual_account_deposit.status_changed | Fires whenever a deposit into a virtual account changes status, from receipt through screening and settlement | Link |