Skip to content
CryptonlyCryptonlyCryptonly

Webhook reference: deposit.statusChanged

POST
/webhooks/deposit.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: deposits.list.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
event
required
string
Allowed values: deposit.statusChanged
data
required
object
id
required
string
accountId
required
string format: uuid
orderId
string
customerId
string
status
required
string
Allowed values: created processing completed suspended failed expired cancelled
cryptoCurrencyCode
required
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
string
expiresAt
required
string
createdAt
required
string
updatedAt
required
string
settlement
object
amountPaid
required
number
amountPaidUsd
required
number
commissionAmount
required
number
commissionAmountUsd
required
number
networkFeeAmount
required
number
networkFeeAmountUsd
required
number
networkFeeCurrencyCode
required
string
netAmount
required
number
netAmountUsd
required
number
txHash
string
completedAt
required
string
previousStatus

Status immediately before this transition.

string
Allowed values: created processing completed suspended failed expired cancelled
depositTransactionHash
string
nullable
actuallyReceivedAmount
number
nullable
actuallyReceivedAmountUsd
number
nullable
timestamp
required

ISO 8601 timestamp when Cryptonly signed and sent the webhook.

string

Examples

Exampledefault

Sample deposit.statusChanged payload

{
  "event": "deposit.statusChanged",
  "data": {
    "id": "c4bdfb4e-a18b-4fb2-9533-182abc04ce15",
    "accountId": "ad04566e-09ed-4cf7-8e36-0e95f8fad274",
    "orderId": "order_webhook_reference_001",
    "status": "completed",
    "cryptoCurrencyCode": "USDT_TRC20",
    "address": "TJn22ewJPN89yNtrnBkagsunbrLnPyQCgs",
    "expiresAt": "2026-10-19T16:17:14.745Z",
    "createdAt": "2026-10-19T16:17:14.745Z",
    "updatedAt": "2026-10-19T16:17:14.745Z",
    "previousStatus": "processing",
    "depositTransactionHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "actuallyReceivedAmount": 50,
    "actuallyReceivedAmountUsd": 50
  },
  "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"
}