Skip to main content
Webhooks let VelaFi push real-time notifications to your server the moment something significant happens — an order changes status, funds arrive in your account, or a global payment moves through its lifecycle. Instead of polling the API repeatedly, you register an HTTPS endpoint once and VelaFi sends an HTTP POST to it with a JSON payload each time a subscribed event fires. This guide covers registering endpoints, verifying the request signature, and acknowledging delivery.
Webhooks are not triggered in the sandbox environment (https://api-test.velafi.com). Test your webhook handler logic by simulating payloads locally, then verify end-to-end in production with low-value transactions.

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 a signature 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:
  1. Extract the signature value from the request header.
  2. Hex-decode the signature value.
  3. Verify it as an RSA-SHA256 (SHA256withRSA, PKCS#1 v1.5) signature over the exact raw request body, using the publicKey from the webhook registration response.
  4. If verification succeeds, process the payload and return {"callbackStatus": "SUCCESS"}.

Webhook payload schemas

Each event type delivers a distinct JSON body to your endpoint.
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.
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.
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 CRYPTO_WITHDRAW_WEBHOOK instead.
The 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 HTTP 2xx 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.