API Reference

Webhooks

Receive real-time notifications when events occur. Configure your endpoint URL in the dashboard.

📬 How webhooks are delivered

  • Each event is sent as an HTTP POST to your configured URL with a JSON body.
  • We use auto-retry so you don’t miss events. Respond with 200OK to confirm receipt; we retry until we get a successful response.

Authentication Methods

Validate every webhook request before processing the payload:

  • Confirm the request comes from Blockfuze using one of the methods below.
  • Only after validation should you trust and process the payload.

Signature verification (HMACSHA512)

  • Each request includes a signature generated from your private keys in the x-main-signature and x-backup-signature headers.
  • Only the signatures you’ve set up are sent (e.g. just x-main-signature if you only created the main API key).
  • Important:
  • Do not compare the signature against a serialized body, only use raw body bytes from the request, as serialization may change the structure of the body.

Static custom header (less secure)

  • Configure a static custom header in webhook config (e.g. a secret in your-custom-header).
  • In your handler, validate the header so you only process requests originating from Blockfuze.

Available Webhooks

Open Webhook Config

Payload Fields

balance
number
Current USDC account balance

Example Body:

{
  "balance": 125.5847
}

Payload Fields

id
bigint
Unique deposit identifier
txid
string
Blockchain transaction ID
from
string
Sender address
to
string
Recipient address
coin
enum int of the crypto coin
cryptoAmount
decimal
Crypto deposit amount
creditAmount
decimal | null
USDC amount credited to your account after fees, this property will be null if the deposit did not complete yet.
depositAmount
decimal | null
USDC value of the deposit, this property will be null if the deposit did not complete yet.
confirmations
integer
Blockchain confirmations
depositStatus
enum int of deposit status
externalUserId
string
externalUserId you provided with DepositAddress endpoint.
externalAvatarFull
string | null
External user avatar URL, this property is null only if you did not call UpdateExternalUser endpoint with AvatarUrl.
externalDisplayName
string | null
External user display name, this property is null only if you did not call UpdateExternalUser endpoint with DisplayName.
processed
boolean
By default this property is false, when you finish processing the deposit on your system call MarkProcessed endpoint to stop receiving updates about this deposit.
lastUpdate
datetime
Last update datetime
created
datetime
Deposit creation datetime

Example Body:

{
  "id": 12345,
  "txid": "0xabc123def456...",
  "from": "0x742d35Cc...",
  "to": "0x8ba1f109...",
  "coin": 0,
  "cryptoAmount": 0.12500006,
  "creditAmount": 1.5,
  "depositAmount": 1.5,
  "confirmations": 12,
  "depositStatus": 2,
  "externalUserId": "user_123",
  "externalAvatarFull": "https://cdn.example.com/avatar.png",
  "externalDisplayName": "John Doe",
  "processed": false,
  "lastUpdate": "2026-03-01T12:34:56.000Z",
  "created": "2026-03-01T10:15:30.000Z"
}

Payload Fields

id
bigint
Unique withdrawal identifier
txid
string
Blockchain transaction ID
from
string | null
Sender address
to
string
Recipient address
coin
enum int of the crypto coin
cryptoAmount
decimal | null
Crypto withdrawal amount, this value will be null when transaction was not sent yet.
withdrawalAmount
decimal | null
USDC value of the withdrawal
fee
decimal | null
USDC value of the blockchain fee that was paid
confirmations
integer
Blockchain confirmations
withdrawalStatus
enum int of WithdrawalStatus
externalWithdrawalId
string
externalWithdrawalId you provided with Withdrawal endpoint.
This value is enforced as unique on our side to prevent duplicate withdrawals.
externalUserId
string
externalUserId you provided with Withdrawal endpoint.
externalAvatarFull
string | null
External user avatar URL, this property is null only if you did not call UpdateExternalUser endpoint with AvatarUrl.
externalDisplayName
string | null
External user display name, this property is null only if you did not call UpdateExternalUser endpoint with DisplayName.
processed
boolean
By default this property is false, when you finish processing the withdrawal on your system call MarkProcessed endpoint to stop receiving updates about this withdrawal.
lastUpdate
datetime
Last update datetime
created
datetime
Withdrawal creation datetime

Example Body:

{
  "id": 12345,
  "txid": "0xabc123def456...",
  "from": "0x742d35Cc...",
  "to": "0x8ba1f109...",
  "coin": 0,
  "cryptoAmount": 0.12500006,
  "withdrawalAmount": 1.5,
  "fee": 0.01,
  "confirmations": 12,
  "withdrawalStatus": 2,
  "externalWithdrawalId": "wd_abc123",
  "externalUserId": "user_123",
  "externalAvatarFull": "https://cdn.example.com/avatar.png",
  "externalDisplayName": "John Doe",
  "processed": false,
  "lastUpdate": "2026-03-01T12:34:56.000Z",
  "created": "2026-03-01T10:15:30.000Z"
}

Enum Reference

Values used in webhook payloads (sent as integers):

Coin

0ETHETH
1USDTUSDT
2USDCUSDC
3DAIDAI
4FDUSDFDUSD
5LINKLINK
8WBTCWBTC
9UNIUNI
10MANAMANA
12BATBAT
13SHIBSHIB
14PEPEPEPE
16USD1USD1
17WBETHWBETH
18CAKECAKE
19WETHWETH
20LEOLEO
21WLFIWLFI
22XAUTXAUT
23AAVEAAVE
24FLOKIFLOKI
25ENSENS
26LDOLDO
27GRTGRT
28COMPCOMP
29SNXSNX
30SUSHISUSHI
31RENDERRENDER

DepositStatus

0Pending
1Rejected
2Confirmed

WithdrawalStatus

0Pending
1Sending
2Sent
3Cancelled
4Error

Best Practices

  • • Return a 2xx status code to acknowledge receipt
  • • Verify webhook payloads match expected transaction IDs
  • • Implement idempotency to handle duplicate deliveries