Withdrawal Status

Emitted when a withdrawal is locked, completed or failed.

Event Types

Event	When Emitted
`withdrawal.order.locked`	Member-initiated on-chain withdrawal submitted; funds removed from the available balance
`withdrawal.order.completed`	Member-initiated on-chain withdrawal paid out
`withdrawal.order.failed`	Member-initiated on-chain withdrawal unsuccessful; all funds returned to the available balance

Delivery Contract

We send a POST request with application/json to your configured endpoint, with a 10-second timeout.
Any 2xx response acknowledges receipt. Non-2xx responses and timeouts trigger retries with backoff.
Four request headers: content-type · z-signature · z-event-id · z-event-type。
Deduplicate by z-event-id — the same event may be delivered more than once.

Event payloads contain only IDs and status

There are no amounts, asset codes, card number fragments or risk-control reasons. This is a security boundary: the webhook endpoint is your service, whose transport and storage we cannot guarantee. The GET /v1/<resource>/{id} endpoint applies API key, scope and on-behalf-of checks. Fetch details using data.id; do not use webhook payloads as the source of amounts for your ledger.

Event Details

withdrawal.order.locked Member-initiated on-chain withdrawal submitted; funds removed from the available balance

When Emitted

Emitted when the member submits the withdrawal in the App. The funds have already left the available balance and entered a separate withdrawal-in-transit bucket, but payout has not occurred. Treat this as a balance-reduction notification, not confirmation that funds reached the destination address. The final result arrives in withdrawal.order.completed / .failed. This is unrelated to the two-phase debiting flow of POST /v1/withdrawals; see the introduction above.

Payload

{
  "event_id": "evt_5e81c0a7f39b4d26ae4713b8c0d5f9a2",
  "event_type": "withdrawal.order.locked",
  "created_at": "2026-08-12T13:05:22Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "withdrawal",
    "id": "8f2a41d6-0c7b-4e39-9a15-63d0c8be7f24",
    "external_member_id": "u_88123",
    "status": "locked",
    "status_version": 1
  }
}

withdrawal.order.completed Member-initiated on-chain withdrawal paid out

When Emitted

Emitted when the upstream confirms payout completion and the settlement journal posts. This is a terminal state. Intermediate states, such as review approval or blockchain broadcast, are deliberately not published: they expose internal workflow, and additional events would suggest that you have something to handle when you do not.

Payload

{
  "event_id": "evt_c47d2be9105f43a8b6e0972d15c8340a",
  "event_type": "withdrawal.order.completed",
  "created_at": "2026-08-12T13:41:57Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "withdrawal",
    "id": "8f2a41d6-0c7b-4e39-9a15-63d0c8be7f24",
    "external_member_id": "u_88123",
    "status": "completed",
    "status_version": 4
  }
}

withdrawal.order.failed Member-initiated on-chain withdrawal unsuccessful; all funds returned to the available balance

When Emitted

Two situations share this event: rejection during our review and upstream payout failure. The member’s next step differs completely: contact support for the former, or resubmit directly for the latter. The event body cannot distinguish them; retrieve the details to identify the case. Fees are fully refunded on failure; we do not retain them.

Payload

{
  "event_id": "evt_0b6e3f9d82c74a15ae37d0561fb92c48",
  "event_type": "withdrawal.order.failed",
  "created_at": "2026-08-12T13:52:10Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "withdrawal",
    "id": "8f2a41d6-0c7b-4e39-9a15-63d0c8be7f24",
    "external_member_id": "u_88123",
    "status": "failed",
    "status_version": 3
  }
}

Signature Verification

The signature verification procedure is the same for all events. See Webhook Overview; use the Signature Debugger to compare signing strings character by character.