Release Notes
Back to All
added

Webhooks: Trade Status and Balance Updates

May 12th, 2025

Release Details

Release Date: May 12th, 2025

Release Type

Informational – optional action from platforms

Summary

Trade status and balance updates are now available via webhooks. This enhancement provides more granular and timely information on trade settlement, the flow of crypto assets, and authoritative changes to account balances held at Zero Hash. To enable this feature, please reach out to your Zero Hash rep and they will configure your Platform accordingly.

New webhook notifications:

  1. trade.status_changed
  2. account_balance.changed

For more information about configuration and handling webhook payloads, visit the Webhooks Overview page.

Trade Status Changed

Trade status notifications provide information about the current trade status. Net Settlement Trades (a.k.a allocation trades) are filtered out and thus don’t generate a notification for the platforms. There are 3 types of status change notifications:

  • accepted - the trade was successfully submitted, accepted, and pending settlement
  • active - within the settlement window, settlement was attempted but is not yet complete
  • terminated - trade was successfully settled; no further status updates will be issued

Note: The x-zh-hook-payload-type must be set to trade_status_changed

While the schema closely follows the existing GET /trades/{trade_id} endpoint, it does NOT contain EVERY field exposed by the endpoint, such as:

  • "accepted_timestamp"
  • "defaulted_timestamp"
  • "settled_timestamp"
  • "last_update"
  • "settlement_timestamp"
  • "expiry_timestamp"
  • "spread_notional"
  • "spread_bps"
  • "session_id"
  • “payment_processor”
  • “fees”
  • “batch_trade_id“

Any additional or supplementary information should still be fetched from GET /trades/{trade_id} endpoint.

Balance Changed

Account balance change notification provides information about the current available account balance. A notification is emitted when the account balance changes for the following account types:

  • available
  • collateral

Note: The x-zh-hook-payload-type must be set to account_balance.changed.

The schema of the event payload will follow the existing private websocket balance updates feed

Relevant Documentation