API Reference

Overview

Basic information about how our webhooks work

Webhooks are a powerful tool for receiving real-time notifications about your payment updates from Zero Hash's systems. By configuring webhooks, you can streamline your workflow and stay informed about events related to your payments.

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.

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 webhooks

When sorting webhooks to determine the sequence by which they happened, use the timestamp field. 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 our the notification we send. You can use that to tell different payloads, check for idempotency and important Webhook Security information.

Header KeyDescription
x-zh-hook-notification-idNotification ID, used for idempotency check
x-zh-hook-payload-typePayload 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