Withdrawal Events

Subscribe to this event by setting the x-zh-hook-payload-type header value to withdrawal.status_changed.

A withdrawal.status_changed webhook is emitted every time a withdrawal request transitions between states - for example, when a request is created, when it is approved, or when it settles.

Withdrawal States

The state field communicates the current stage of the withdrawal request in zerohash's processing pipeline. Values are returned in lowercase.

State	Description
`pending_trade`	Withdrawal was created against a trade that has not been activated. It will not progress until the trade is activated.
`pending`	Withdrawal is awaiting approval from an Authorized Signer. It will not progress until approved.
`approved`	Withdrawal has been approved and is queued for settlement.
`rejected`	Withdrawal will not be settled. Terminal.
`compliance_risk`	Withdrawal has been flagged by a compliance review and is not eligible for settlement.
`compliance_violation_sanctioned`	Withdrawal has been blocked and will not be settled. Terminal.
`settled`	Withdrawal has been settled and the account debited. Terminal.

Payload Schema

Field	Type	Description
`withdrawal_id`	string (uuid)	Unique identifier for the withdrawal. Use this ID to look up the withdrawal via `GET /withdrawals/requests/{id}`.
`participant_code`	string	Participant code of the customer that owns the debited account.
`platform_code`	string	Platform the withdrawal belongs to.
`account_id`	string	Identifier of the zerohash account that will be debited.
`asset`	string	Ticker symbol of the withdrawn asset (i.e. `BTC`, `ETH`, `USDC`).
`amount`	string (decimal)	Amount of the asset withdrawn. Represented as a string to preserve precision.
`state`	string	Current withdrawal state. See Withdrawal States for possible values.
`onchain_transaction_status`	string	`pending` or `confirmed`. Reported independently of `state`. Crypto withdrawals only.
`transaction_hash`	string	On-chain transaction hash associated with the withdrawal. Omitted until the transaction is broadcast.
`destination_address`	string	On-chain address receiving the withdrawal.
`trade_id`	string	Trade the request was created against. Omitted if not supplied at creation.
`timestamp`	integer	Unix timestamp (seconds) of when this state change occurred. Use this value to determine the relative ordering of events.

Example Payload

{
    "withdrawal_id": "f6a1c2c4-2a9e-4a01-9b0f-7b9e2c5d8e11",
    "account_id": "PART123.general",
    "participant_code": "PART123",
    "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "state": "approved",
    "onchain_transaction_status": "pending",
    "asset": "ETH",
    "amount": "2.5",
    "destination_address": "0x9876543210fedcba9876543210fedcba98765432",
    "timestamp": 1745554838
}

Auth Withdrawal Events

Subscribe to this event by setting the x-zh-hook-payload-type header value to auth_withdrawal.status_changed.

An auth_withdrawal.status_changed webhook is emitted every time a deposit submitted through the Auth product transitions states. In the context of Auth, they indicate the stages zerohash can detect during the lifecycle of an Auth Withdrawal.

Because the destination is either an Auth Partner such as Robinhood or a self-custody wallet such as MetaMask, visibility into exact status updates varies by connection.

Auth Withdrawal States

The state field communicates the current stage of the deposit in zerohash's processing pipeline. Values are returned in lowercase.

State	Description
`pending`	Withdrawal has been created and is pending submission in the AUTH flow - user is in progress
`submitted`	Withdrawal has been successfully broadcasted by zerohash on-chain and awaiting sufficient confirmation
`2fa_pending`	Pending 2FA input and validation (if applicable, varies by AUTH connection)
`confirmed`	Sufficient on-chain confirmations received. Terminal for AUTH connections where zerohash cannot confirm funds availability.
`completed`	Confirmation funds are available for the customer. Terminal for AUTH connections where zerohash can confirm funds availability.
`failed`	Transaction was not successfully sent on-chain and must be retried. Terminal.
`abandoned`	Transaction was not completed within the defined timeout period. Terminal.

Payload Schema

Field	Type	Details
`withdrawal_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	Receiving address at Auth Partner or wallet
`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
`created_at`	string (ISO 8601)	Withdrawal creation timestamp
`updated_at`	string (ISO 8601)	Timestamp of this state change

Example Payload

{
  "withdrawal_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"
}