Withdrawal webhooks

OpenFX delivers a signed webhook event when a withdrawal transitions to a notable state. Three event types cover the withdrawal lifecycle:

withdrawal.processing — the withdrawal has been accepted and is moving through the payment rail.
withdrawal.completed — the withdrawal has settled successfully.
withdrawal.failed — the withdrawal has reached a terminal failure state.

All three event types carry a single Withdrawal object in data that follows the same field conventions as v3 REST API responses — camelCase fields, string amounts, RFC 3339 timestamps. The data object matches what GET /v3/fx/withdrawals/{id} returns for the same record.

Event envelope

This routing-only example collapses data to an empty object. It deliberately omits the required Withdrawal fields shown in the complete, schema-checked examples below.

{
  "id": "evt_7m4VsfRw4pGrS76WYj5tnx",
  "type": "withdrawals",
  "eventType": "withdrawal.completed",
  "createdAt": "2026-04-28T08:32:50.618Z",
  "data": {}
}

Field	Type	Notes
`id`	string (readable ID, `evt_` prefix)	Unique per event. Deduplicate on this field.
`type`	string	Resource noun: always `"withdrawals"` for withdrawal events. Use it to route by resource family.
`eventType`	string	Dotted action: `"withdrawal.processing"`, `"withdrawal.completed"`, or `"withdrawal.failed"`.
`createdAt`	string (RFC 3339, ms, UTC)	When OpenFX created the event.
`data`	object	The Withdrawal resource in its current state. See field reference below.

Payload

Fiat (Fedwire / SEPA / SWIFT / ACH)
Stablecoin (USDC / USDT / EURC)

{
  "id": "evt_7m4VsfRw4pGrS76WYj5tnx",
  "type": "withdrawals",
  "eventType": "withdrawal.completed",
  "createdAt": "2026-04-28T08:32:50.618Z",
  "data": {
    "object": "withdrawal",
    "id": "wtd_6SATV6VSUdBTttHWBmCYjD",
    "currency": "USD",
    "assetType": "FIAT",
    "withdrawalAmount": "5000.00",
    "status": "COMPLETED",
    "network": null,
    "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
    "estimatedCompletionAt": null,
    "transactionHash": null,
    "paymentDetails": {
      "FEDWIRE": {
        "imad": "20260428B1QGC07C001234",
        "omad": "20260428L1B7012C003456"
      }
    },
    "actorId": "usr_7m4VsfRw4pGrS76WYj5tnx",
    "actorEmail": "[email protected]",
    "comments": "Invoice 1042",
    "createdAt": "2026-04-28T08:28:05.112Z"
  }
}

Field	Notes
`assetType`	`"FIAT"` for bank-rail withdrawals.
`network`	`null` for fiat withdrawals — there is no chain to read.
`withdrawalAccountId`	Readable ID (`wac_` prefix) of the verified withdrawal account this payment was sent to.
`paymentDetails`	Network-specific identifiers populated once the withdrawal reaches a terminal state, keyed by transfer type (e.g. `FEDWIRE` IMAD/OMAD). Present only for fiat withdrawals.
`actorId` / `actorEmail`	Identify who initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal OpenFX operator.
`comments`	Optional notes recorded with the withdrawal. `null` when none were recorded.
`withdrawalAmount`	String decimal — e.g. `"5000.00"`. Always positive.

{
  "id": "evt_7m4VsfRw4pGrS76WYj5tnx",
  "type": "withdrawals",
  "eventType": "withdrawal.completed",
  "createdAt": "2026-04-28T08:32:50.618Z",
  "data": {
    "object": "withdrawal",
    "id": "wtd_6SATV6VSUdBTttHWBmCYjD",
    "currency": "USDT",
    "assetType": "CRYPTO",
    "withdrawalAmount": "10000.00",
    "status": "COMPLETED",
    "network": "ETHEREUM",
    "withdrawalAccountId": "wac_NDqQ9LmcUASpnHR6CTvdkk",
    "estimatedCompletionAt": null,
    "transactionHash": "0xdef456abc7890123def456abc7890123def456abc7890123def456abc78901",
    "paymentDetails": null,
    "actorId": "usr_7m4VsfRw4pGrS76WYj5tnx",
    "actorEmail": "[email protected]",
    "comments": null,
    "createdAt": "2026-04-28T08:28:05.112Z"
  }
}

Field	Notes
`network`	The chain the withdrawal settled over (e.g. `ETHEREUM`, `SOLANA`, `TRON`; see Supported networks).
`transactionHash`	The on-chain transaction hash once broadcast. `null` before the chain leg lands.
`paymentDetails`	`null` for crypto withdrawals — populated only for fiat.
`withdrawalAmount`	String decimal. Always positive.

status is an unconstrained string reflecting the current lifecycle state (no closed enum is documented) — observed values include PENDING, PROCESSING, COMPLETED, FAILED, RETURNED, and CANCELED. The webhook catalog ships withdrawal.processing, withdrawal.completed, and withdrawal.failed events; the v3 API surfaces the same record with a matching status via GET /v3/fx/withdrawals/{id}.

Withdrawal resource fields

Field	Type	Notes
`object`	string	Always `"withdrawal"`.
`id`	string (readable ID, `wtd_` prefix)	Withdrawal resource ID.
`currency`	string	ISO 4217 currency code or stablecoin ticker.
`assetType`	string	Asset class: `"CRYPTO"` for on-chain, `"FIAT"` for bank rails.
`withdrawalAmount`	string	Decimal string, e.g. `"5000.00"`. Always positive.
`status`	string	Unconstrained lifecycle state string; no closed enum is documented.
`network`	string \| null	Network the crypto withdrawal settled over, e.g. `ETHEREUM`. `null` for fiat withdrawals.
`withdrawalAccountId`	string (readable ID, `wac_` prefix)	References the `WithdrawalAccount.id` this withdrawal pays to.
`estimatedCompletionAt`	string \| null (RFC 3339, ms, UTC)	When the withdrawal is expected to settle. `null` if there is no ETA yet.
`transactionHash`	string \| null	On-chain transaction hash for crypto withdrawals once broadcast. `null` for fiat or before the chain leg lands.
`paymentDetails`	object \| null	Network-specific identifiers populated once the withdrawal reaches a terminal state, keyed by transfer type. Present only for fiat withdrawals; omitted entirely for crypto.
`actorId`	string (readable ID, `usr_` prefix)	ID of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal OpenFX operator.
`actorEmail`	string	Email of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal OpenFX operator.
`comments`	string \| null	Optional notes or comments about the withdrawal. `null` when none were recorded.
`createdAt`	string (RFC 3339, ms, UTC)	When the withdrawal record was created.
`metadata`	object	Only present when you supplied `metadata` on the originating `POST /v3/fx/withdrawals` request. See Withdrawal metadata.

Idempotency on your side

Same pattern as deposit webhooks — use the event id for dedup. See Deposit webhooks: idempotency on your side.

Failed withdrawals

When a withdrawal terminates as FAILED, the withdrawal.failed event is delivered with data.status: "FAILED". If you need the latest state — for example to confirm a subsequent RETURNED, or after a missed delivery — re-fetch with GET /v3/fx/withdrawals/{id} using the id from data.id. See Withdrawal lifecycle: when a withdrawal is stuck for the triage runbook.

Verification

Every event is signed in the X-OpenFX-Signature header using HMAC-SHA256 over the signed payload timestamp + "." + raw_body. Always verify with a constant-time comparator before reading any payload field. See Webhook authentication.

What’s next

Webhook authentication

Signature verification with constant-time comparators.

Deposit webhooks

The other side of the deposit/withdrawal lifecycle.

Withdrawal lifecycle

State machine + stuck-withdrawal runbook.

Errors

Stable error codes and the retry triage matrix.

Get Started

Platform basics

FX

Operations

Glossary

Webhooks

Withdrawal webhooks

Event envelope

Payload

Withdrawal resource fields

Idempotency on your side

Failed withdrawals

Verification

What’s next

Webhook authentication

Deposit webhooks

Withdrawal lifecycle

Errors

​Event envelope

​Payload

​Withdrawal resource fields

​Idempotency on your side

​Failed withdrawals

​Verification

​What’s next

Webhook authentication

Deposit webhooks

Withdrawal lifecycle

Errors

Event envelope

Payload

Withdrawal resource fields

Idempotency on your side

Failed withdrawals

Verification

What’s next