Subscribe to this event by setting the x-zh-hook-payload-type header value to deposit.status_changed.
A deposit.status_changed webhook is emitted every time a blockchain deposit transitions between states — for example, when a transaction is first detected on-chain, when it receives enough confirmations, or when the funds are credited to the customer's account.
Deposit States
The state field communicates the current stage of the deposit in Zero Hash's processing pipeline. Values are returned in lowercase.
| State | Description |
|---|---|
initial | Deposit has been detected on-chain and recorded, awaiting confirmations. |
confirmed | Deposit has received sufficient on-chain confirmations. |
pending_compliance_review | Deposit is being held for a compliance review before funds can be credited. |
pending_approval | Deposit exceeds a configured threshold and requires manual approval before it can be settled. |
pending_settlement | Deposit has passed all reviews and is queued to be credited to the customer's account. |
completed | Funds have been credited to the customer's account. This is a terminal state. |
quarantined | Deposit has been quarantined and will not be credited without manual intervention. This is a terminal state. |
recovery_quarantine | Deposit has been placed into recovery quarantine pending investigation. |
Example Payload
{
"deposit_id": "f6a1c2c4-2a9e-4a01-9b0f-7b9e2c5d8e11",
"account_id": "PART123.general",
"participant_code": "PART123",
"transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"state": "confirmed",
"asset": "ETH",
"amount": "2.5",
"source_address": "0x1234567890abcdef1234567890abcdef12345678",
"received_address": "0x9876543210fedcba9876543210fedcba98765432",
"timestamp": 1745554838
}Payload Fields
| Field | Type | Description |
|---|---|---|
deposit_id | string | Unique identifier for the deposit. Use this ID to look up the deposit via GET /deposits/crypto/{deposit_id}. |
account_id | string | Identifier of the Zero Hash account that will be credited with the deposited funds. |
participant_code | string | Participant code of the customer that owns the receiving account. |
transaction_hash | string | On-chain transaction hash associated with the deposit. |
state | string | Current deposit state. See Deposit States for possible values. |
asset | string | Ticker symbol of the deposited asset (e.g., BTC, ETH, USDC). |
amount | string (decimal) | Amount of the asset that was deposited. Represented as a string to preserve precision. |
source_address | string | On-chain address that funded the deposit. |
received_address | string | On-chain address owned by Zero Hash that received the deposit. |
timestamp | integer | Unix timestamp (seconds) of when this state change occurred. Use this value to determine the relative ordering of events. |