Overview

Deposits emit one of two webhook payload types depending on how the deposit was initiated. Standard blockchain deposits emit x-zh-hook-payload-type header value of deposit.status_changed, while deposits submitted through the AUTH product (e.g., via AUTH Providers like Robinhood) emit auth_deposit.status_changed. Both events track a deposit as it moves from on-chain detection through compliance review to final crediting, but each uses its own set of state values reflecting its distinct processing pipeline. The table below consolidates the possible states across both deposit types and which type(s) each state applies to.

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. state_reason is the list of potential reasons you may receive for the given state. Values are returned in lowercase.

State	State Reason	Description	Terminal State
`confirmed`	`deposit_detected_onchain`	Deposit has received sufficient confirmations and is complete on-chain	-
`pending_compliance`	`pending_compliance_screening`	Deposit waiting for compliance screening	-
`pending_compliance_review`	`required_travel_rule_info`	Deposit held for compliance review before funds can be credited	-
`pending_approval`	`auth_approval_required` `high_notional_value`	Deposit exceeds a configured threshold and requires manual approval before settlement	-
`pending_settlement`	`complete_valid_deposit` `auth_approval_confirmed` `admin_approved`	Deposit has passed all reviews and is queued for crediting	-
`completed`	`complete_valid_deposit` `auth_approval_confirmed` `admin_approved` `travel_rule_info_received` `manual_compliance_approved` `manual_compliance_recover`	Funds have been credited to the customer account.	✅
`quarantined`	-	Funds will not be credited without manual intervention.	✅
`recovery_quarantine`	`auth_approval_rejected` `admin_rejected` `travel_rule_info_timeout` `manual_compliance_rejected`	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	Terminal State
`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
`reference_id`	string	Platform provided id for the transaction. Present if a `reference_id` was provided at JWT generation time.
`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
`fees`	object	Fee breakdown for the withdrawal. Contents depend on `state` and `fee_payment_model`. In `pending` state, only fee_payment_model is guaranteed; network and withdrawal amounts are populated once the transaction is confirmed, `NETTED` withdrawals may carry fee amounts earlier.
`fees.estimated_network`	object	The estimated network fee for the deposit based on the transaction parameters (amount, asset, network). Actual deposit fees will be displayed once transaction is submitted in the `deposit` object.
`fees.deposit`	object	Actual deposit fees paid as part of the transaction. This amount may differ from estimated fees.
`crypto_amount`	string (decimal)	Fee amount denominated in the underlying crypto asset.
`crypto_asset`	string	Underlying crypto asset used to pay the fee
`notional_amount`	string (decimal)	Fee amount converted to the notional currency at the time of the event
`notional_currency`	string	Currency of `notional_amount`
`estimated`	boolean	Returns `true` if the fee object is estimated; returns `false` if the fees are the real fees incurred on the transaction.
`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",
  "reference_id": "f4c9c7ac-396c-43ab-b694-97d9779ba60e",
  "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",
  "reference_id": "f4c9c7ac-396c-43ab-b694-97d9779ba60e",
  "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..."
}