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
`confirmed`	Sufficient on-chain confirmations received. Terminal for AUTH connections where zerohash cannot confirm funds availability.
`failed`	Transaction was not successfully sent on-chain and must be retried. Terminal.

Payload Schema

Field	Type	Details
`withdrawal_id`	string (uuid)	Unique withdrawal identifier
`parent_link_id`	string (uuid)	Identifier of the parent resource that originated this withdrawal (e.g. the payment ID when the withdrawal was triggered by a payments flow). Use it to correlate `auth_withdrawal.status_changed` events with payments webhooks for the same transaction. Omitted when the withdrawal has no parent resource.
`reference_id`	string	Platform provided id for the transaction. Present if a `reference_id` is supplied when generating a JWT token
`participant_code`	string	Customer participant code owning the withdrawal
`platform_code`	string	Platform the withdrawal belongs to
`connection_id`	string (uuid)	AUTH connection tied to the deposit. Renders as an all-zero UUID (`00000000-...`), not `null` or omitted, when the withdrawal has no connection (e.g. manual/legacy withdrawals)
`source_type`	string	`CUSTODIAL`, `NON_CUSTODIAL`, or `MANUAL`. Omitted if not set
`source_integration`	string	Target integration of the AUTH withdrawal
`account_label`	string	Subledger for which the withdrawal was executed from. The default if not specified in the withdrawal is `general`
`state`	string	Current withdrawal state (see table above), always lowercase
`symbol`	string	Asset symbol (e.g. `USDC.ETH`)
`amount`	string (decimal)	Withdrawal amount in asset denomination
`destination_address`	string	Receiving address at AUTH Partner or wallet
`transaction_hash`	string	On-chain transaction hash. Omitted until matched on-chain (absent for `pending`, `submitted`, `archived`)
`block_number`	string	Same omission rule as `transaction_hash`
`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.
`fee.fee_payment_model`	string	How fees are charged. `NETTED`: fees are deducted from the withdrawal amount, so the recipient receives amount minus fees. `ADDITIVE`: fees are charged on top of the withdrawal amount, so the recipient receives the full amount.
`fee.network`	String	Blockchain network fee (gas) paid to broadcast the transaction on-chain. Omitted until amounts are known (typically absent in `pending` state for `ADDITIVE`.
`fee.withdrawal`	string	zerohash withdrawal fee charged for processing the withdrawal. Omitted until amounts are known. May be "0" when no withdrawal fee applies.
`<network\|withdrawl>.crypto_amount`	string (decimal)	Fee amount denominated in the underlying crypto asset.
`<network\|withdrawal>.crypto_asset`	string	Underlying crypto asset used to pay the fee
`<network\|withdrawal>.notional_amount`	string (decimal)	Fee amount converted to the notional currency at the time of the event
<network\|withdrawal>.notional_currency	string	Currency of `notional_amount`
`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": "3f0d6b2e-9c41-4b7a-8e55-2d1a7c9f4b60",
    "parent_link_id": "1b64084e-3cb1-4e9a-920e-4198c0b26c85",
    "reference_id": "d4b2d2a6-1301-4797-9539-c966aea47603",
    "participant_code": "PART123",
    "platform_code": "PLAT01",
    "connection_id": "cf215489-ffb3-41c2-9216-18eec55184c6",
    "source_type": "NON_CUSTODIAL",
    "source_integration": "metamask",
    "account_label": "general",
    "state": "confirmed",
    "symbol": "USDC",
    "amount": "25",
    "destination_address": "0x4411420BdDf0752f1eD50ACf0951F1fECdc0eB77",
    "transaction_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "block_number": "21345678",
    "fees": {
        "fee_payment_model": "NETTED",
        "network": {
            "amount": "0.0021",
            "asset": "ETH",
            "crypto_amount": "0.0021",
            "crypto_asset": "ETH",
            "notional_amount": "5.12",
            "notional_currency": "USD",
            "estimated": false
        },
        "withdrawal": {
            "amount": "0.50",
            "asset": "USDC",
            "crypto_amount": "0.50",
            "crypto_asset": "USDC",
            "notional_amount": "0.50",
            "notional_currency": "USD",
            "estimated": false
        }
    },
    "created_at": "2026-10-06T14:02:11Z",
    "updated_at": "2026-10-06T14:05:48Z"
}