Available event types
Register a separate webhook for each event type you want to receive. Creating a webhook is rejected while an active webhook already exists for that event type, and a webhook receives its event for every merchant under your account. VelaFi supports the following event types:ORDER_WEBHOOK
Fires on status changes for fiat-to-crypto (on-ramp) and crypto-to-fiat (off-ramp) orders created through the API.
GLOBAL_PAYMENT_WEBHOOK
Fires on status changes for fiat-to-fiat global payment orders created through the API.
FUNDING_WEBHOOK
Fires when a funding record (a fiat deposit, fiat withdrawal, crypto purchase, or internal transfer on the merchant’s fiat (Pending Fund) account) is completed, canceled, or refunded. Crypto wallet withdrawals are covered by
CRYPTO_WITHDRAW_WEBHOOK instead.ON_RAMP_WITHDRAW_WEBHOOK
Fires when VelaFi has withdrawn the crypto from a completed API on-ramp order to the order’s destination wallet address.
STABLE_COIN_PAYMENT_WEBHOOK
Fires when a stablecoin payment order is confirmed.
CRYPTO_WITHDRAW_WEBHOOK
Fires when a crypto withdrawal from a merchant wallet succeeds, fails, or is cancelled.
Register a webhook endpoint
Verify the webhook signature
Every request VelaFi sends to your endpoint includes asignature header. The value is an RSA-SHA256 signature of the raw request body, encoded as a hexadecimal string. Always verify this signature before processing the payload to ensure the request genuinely came from VelaFi.
The verification steps are:
- Extract the
signaturevalue from the request header. - Hex-decode the
signaturevalue. - Verify it as an RSA-SHA256 (
SHA256withRSA, PKCS#1 v1.5) signature over the exact raw request body, using thepublicKeyfrom the webhook registration response. - If verification succeeds, process the payload and return
{"callbackStatus": "SUCCESS"}.
- Java
- Python
- JavaScript
Webhook payload schemas
Each event type delivers a distinct JSON body to your endpoint.ORDER_WEBHOOK — on-ramp and off-ramp orders
ORDER_WEBHOOK — on-ramp and off-ramp orders
VelaFi sends this payload on status changes for fiat-to-crypto and crypto-to-fiat orders created through the API. This is an abbreviated example; see Order Event for every field.
orderType is BUY for on-ramp orders and SELL for off-ramp orders. Only some statuses are sent, and rejected or timed-out orders are sent as 70. See Order Event for the statuses that are sent.GLOBAL_PAYMENT_WEBHOOK — fiat-to-fiat orders
GLOBAL_PAYMENT_WEBHOOK — fiat-to-fiat orders
VelaFi sends this payload on status changes for fiat-to-fiat global payment orders created through the API.
orderStatus uses the same codes as the Global Payments order detail endpoint, but only the statuses listed on Global Payment Event are sent.FUNDING_WEBHOOK — merchant funding events
FUNDING_WEBHOOK — merchant funding events
VelaFi sends this payload when a fiat deposit, fiat withdrawal, crypto purchase, or internal transfer on your merchant’s fiat (Pending Fund) account is completed, canceled, or refunded. Crypto wallet withdrawals are covered by The
CRYPTO_WITHDRAW_WEBHOOK instead.type field is one of DEPOSIT, WITHDRAW, BUY_CRYPTO, TRANSFER_IN, or TRANSFER_OUT. The status field is 2 (completed), 3 (canceled), or 4 (refunded). Pending records are not sent.Acknowledge receipt
Your endpoint must return an HTTP2xx response (for example 200) with the following JSON body to confirm that the notification was received and processed successfully. If VelaFi does not receive a SUCCESS acknowledgement, for example because your endpoint did not respond within 6 seconds, it retries delivery, for three attempts in total. See Delivery and Retries for the schedule, duplicate handling, and ordering.
Return
{"callbackStatus": "SUCCESS"} as soon as you have verified the signature and persisted the event. Perform any downstream processing asynchronously to avoid timeouts that could trigger unnecessary retries.
