Skip to content
CryptonlyCryptonlyCryptonly

Webhook reference: withdrawal.statusChanged

POST
/webhooks/withdrawal.statusChanged

Reference schema for outbound webhooks Cryptonly POSTs to your configured HTTPS webhookUrl. Each delivery includes an x-webhook-signature header (HMAC-SHA256 over the raw JSON body). This route exists for Swagger documentation only; implement verification and handling on your own server.

Required scope: withdrawals.list.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
event
required
string
Allowed values: withdrawal.statusChanged
data
required
object
id
required
string
orderId
required
string
accountId
required
string
cryptoCurrencyCode
required

Currency code.

string
Allowed values: USDT_TRC20 USDT_ERC20 USDT_BEP20 USDC_ERC20 USDC_BEP20 USDC_BASE EURC_BASE LINK_ERC20 LINK_BEP20 ETH TRX BNB BTC ETH_BASE
address
required

Destination wallet address

string
transactionHash

On-chain transaction hash

string
nullable
amount
required

Withdrawal amount in cryptoCurrencyCode

number
amountUsd
required

Withdrawal amount in USD

number
status
required
string
Allowed values: created processing completed failed cancelled
convertId

Optional funding currency_conversion that topped up the withdrawal asset before this withdrawal debit (auto-convert).

string format: uuid
nullable
feeAmount
required

Network fee debited from the user in cryptoCurrencyCode (same value used in debitedAmount = amount + this fee)

number
feeAmountUsd
required

Same fee, snapshotted to USD at commit time

number
debitedAmount
required

Exact total debited in cryptoCurrencyCode (on-chain amount + on-chain fee)

number
customData
object
webhookUrl
string
nullable
source

Commit channel; omitted when unknown (rows created before this metadata existed).

string
Allowed values: api admin_panel
createdAt
required

ISO 8601 timestamp.

string
updatedAt
required

ISO 8601 timestamp.

string
quoteId
required

Opaque id from the quote phase; equals the committed network transfer id when set.

string format: uuid
nullable
transferId
required

Network transfer backing this withdrawal once committed.

string format: uuid
nullable
previousStatus

Status immediately before this transition.

string
Allowed values: created processing completed failed cancelled
timestamp
required

ISO 8601 timestamp when Cryptonly signed and sent the webhook.

string

Examples

Exampledefault

Sample withdrawal.statusChanged payload

{
  "event": "withdrawal.statusChanged",
  "data": {
    "id": "a1630edf-cef9-46d5-af2b-d882c35075f7",
    "orderId": "order_webhook_reference_001",
    "accountId": "f80e79ba-6815-4216-80df-f51c4a651e37",
    "cryptoCurrencyCode": "ETH",
    "address": "0x1111111111111111111111111111111111111111",
    "amount": 100,
    "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "completed",
    "previousStatus": "processing",
    "convertId": null,
    "feeAmount": 1,
    "feeAmountUsd": 1,
    "amountUsd": 100,
    "debitedAmount": 101,
    "createdAt": "2026-10-19T16:17:14.745Z",
    "updatedAt": "2026-10-19T16:17:14.745Z",
    "quoteId": "42d73f45-6479-48ad-92fa-f6a6b13f05b2",
    "transferId": "4270c088-ce18-451f-8a60-495b258689fc",
    "source": "api"
  },
  "timestamp": "2026-01-01T12:00:00.000Z"
}

Responses

Section titled “Responses”

200

Section titled “200”

Reference endpoint acknowledged.

400

Section titled “400”

Request validation failed (e.g. missing or malformed body / query).

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

401

Section titled “401”

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

403

Section titled “403”

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

429

Section titled “429”

Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

500

Section titled “500”

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}