--- updatedAt: 2026-10-08T01:51:36.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # AUTH Withdrawal Status Updates # 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](https://docs.zerohash.com/zerohash/docs/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. | | `.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` | | `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 ```json { "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" } ```