{
  "id": "evt_wth004",
  "type": "withdrawal.failed",
  "data": {
    "sideshiftAccountId": "user_a1b2c3d4",
    "externalId": "ext_user_456",
    "amountCents": 25000,
    "feeCents": 0,
    "netAmountCents": 25000,
    "currency": "usd",
    "paymentId": "wdrl_abc123",
    "status": "failed",
    "metadata": {
      "withdrawalId": "wdrl_abc123",
      "errorCode": "account_closed",
      "errorMessage": "The receiving bank rejected the transfer because the account is closed.",
      "previousStatus": "in_transit"
    }
  },
  "timestamp": "2026-05-13T05:00:00.000Z"
}

Withdrawalfailed

Derived alias of withdrawal.updated for the two terminal states where the money did not arrive: failed (the payout was returned, usually by the receiving bank) and denied (SideShift or the payout provider refused it). Unlike withdrawal.completed, status is NOT normalized — read it to tell the two apart.

metadata.errorCode and metadata.errorMessage carry the underlying reason when the payout provider supplies one, which is what makes this event triageable without asking the user what happened.

A canceled withdrawal is not a failure and is delivered on withdrawal.updated only. Both failed and denied are terminal: the withdrawal will not transition again.

A withdrawal.completed subscription implies this event — if you asked to hear when a payout lands, you receive the bounce too, with no subscription change. Ignore unknown type values and this is a no-op until you handle it.

WEBHOOK

withdrawal.failed

{
  "id": "evt_wth004",
  "type": "withdrawal.failed",
  "data": {
    "sideshiftAccountId": "user_a1b2c3d4",
    "externalId": "ext_user_456",
    "amountCents": 25000,
    "feeCents": 0,
    "netAmountCents": 25000,
    "currency": "usd",
    "paymentId": "wdrl_abc123",
    "status": "failed",
    "metadata": {
      "withdrawalId": "wdrl_abc123",
      "errorCode": "account_closed",
      "errorMessage": "The receiving bank rejected the transfer because the account is closed.",
      "previousStatus": "in_transit"
    }
  },
  "timestamp": "2026-05-13T05:00:00.000Z"
}

Authorizations

x-api-key

string

header

required

Your SideShift Connect API key (sk_live_* or sk_test_*). Generate from Settings → Connect.

Body

application/json

string

type

string

Example:

"withdrawal.failed"

data

object

Show child attributes

timestamp

string<date-time>

Response

200

Webhook acknowledged

⌘I