Deposit Events
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 Statuses
The state field communicates the current stage of the deposit in zerohash's processing pipeline. Values are returned in lowercase.
| State | Description |
|---|---|
CONFIRMED | Deposit has received sufficient confirmations and is complete on-chain |
PENDING_COMPLIANCE_REVIEW | Deposit held for compliance review before funds can be credited |
PENDING_APPROVAL | Deposit exceeds a configured threshold and requires manual approval before settlement |
PENDING_SETTLEMENT | Deposit has passed all reviews and is queued for crediting |
COMPLETED | Funds have been credited to the customer account. Terminal. |
QUARANTINED | Funds will not be credited without manual intervention. Terminal. |
RECOVERY_QUARANTINE | Funds have been placed into recovery quarantine pending investigation. Possible scenarios include amounts received below minimum or outside of transaction limits, asset/network mismatch, conversion failures (rare) |
Payload Schema
| 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. |
state_reason | string | Why the deposit is in it's current state. Pairs with state to give the full outcome without inspecting history. |
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. |
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
}AUTH Deposit Events
Subscribe to this event by setting the x-zh-hook-payload-type header value to auth_deposit.status_changed.
An auth_deposit.status_changed webhook is emitted every time a deposit submitted through the AUTH product transitions states. These webhooks emit for all of the standard events of Deposit Status Updates, but in the context of AUTH, they indicate the first point where zerohash can detect deposits given that the transactions originate from AUTH Providers such as Robinhood.
AUTH Deposit States
The state field communicates the current stage of the deposit in zerohash's processing pipeline. Values are returned in lowercase.
| State | Description |
|---|---|
pending | Deposit has been created and is pending submission in the AUTH flow - user is in progress |
submitted | Deposit has been successfully submitted by AUTH Provider and awaiting on-chain detection |
2fa_pending | Deposit is pending 2FA input and validation |
confirmed | Deposit has received sufficient on-chain confirmations. |
failed | Deposit has failed - recoverable funds will be available within the /recovery_quarantine subledger |
unexpected | Funds were marked as unexpected by the platform and will be made available for recovery within the /recovery_quarantine subledger |
abandoned | Transaction was not successfully matched within the defined timeout period and has been considered abandoned. Funds will be made available in the /recovery_quarantine subledger. |
archived | Transaction has been archived and is no longer in a processing state |
account_match_pending | Account name matching is in progress pending a final match. |
account_match_timeout | Account name matching for travel rule has timed out as deposit could not be found for the transaction ID. Funds will be made available in /recovery_quarantine subledger. |
account_match_failed | Account matching has failed. Funds have been made available in the /recovery_quarantine subledger. |
Payload Schema
| Field | Type | Details |
|---|---|---|
deposit_id | string (uuid) | Unique deposit identifier |
participant_code | string | Customer participant code owning the deposit |
platform_code | string | Platform the deposit belongs to |
amount | string (decimal) | Deposit amount |
symbol | string | Asset symbol (e.g. USDC.ETH) |
state | string | Current deposit state (see table above), always lowercase |
connection_id | string (uuid) | AUTH connection tied to the deposit. Renders as an all-zero UUID (00000000-...), not null or omitted, when the deposit has no connection (e.g. manual/legacy deposits) |
source_type | string | CUSTODIAL, NON_CUSTODIAL, or MANUAL. Omitted if not set |
source_integration | string | Source integration of the AUTH deposit |
transaction_hash | string | On-chain transaction hash. Omitted until matched on-chain (absent for pending, submitted, 2fa_pending, archived) |
block_number | string | Same omission rule as transaction_hash |
destination_address | string | zerohash-owned receiving address |
failure_reason | string or null | A failed state from a non-account-validation cause (e.g. address not whitelisted) |
account_label | string | Free-text label set at deposit creation. Omitted if empty |
travel_rule_match_result | string | pending, valid, invalid, error, or timeout. Only present once the deposit has gone through account validation |
created_at | string (ISO 8601) | Deposit creation timestamp |
updated_at | string (ISO 8601) | Timestamp of this state change |
Example Payload
{
"deposit_id": "f6a1c2c4-2a9e-4a01-9b0f-7b9e2c5d8e11",
"participant_code": "PART456",
"platform_code": "PLAT123",
"amount": "100.00",
"symbol": "USDC.ETH",
"state": "confirmed",
"connection_id": "3f29a1e0-1c44-4b3a-9d2e-8a7c6b5f4e10",
"source_type": "CUSTODIAL",
"source_integration": "cbase",
"transaction_hash": "0xabcdef1234567890...",
"block_number": "18500000",
"destination_address": "0xZHwallet...",
"failure_reason": null,
"account_label": "primary",
"created_at": "2026-05-05T00:00:00Z",
"updated_at": "2026-05-05T00:00:01Z"
}Account-matching states include travel_rule_match_result in addition to the fields above:
{
"deposit_id": "f6a1c2c4-2a9e-4a01-9b0f-7b9e2c5d8e11",
"participant_code": "PART456",
"platform_code": "PLAT123",
"amount": "100.00",
"symbol": "USDC.ETH",
"state": "account_match_failed",
"connection_id": "3f29a1e0-1c44-4b3a-9d2e-8a7c6b5f4e10",
"source_type": "CUSTODIAL",
"source_integration": "cbase",
"transaction_hash": "0xabcdef1234567890...",
"block_number": "18500000",
"destination_address": "0xZHwallet...",