Webhooks
Create a Webhook
Register a callback URL to receive real-time event notifications for orders, funding activity, global payments, stablecoin payments, or crypto withdrawals.
POST
/
v2
/
webhook
Create a Webhook
curl --request POST \
--url https://api-test.velafi.com/v2/webhook \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"eventType": "<string>",
"url": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/webhook"
payload = {
"eventType": "<string>",
"url": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({eventType: '<string>', url: '<string>'})
};
fetch('https://api-test.velafi.com/v2/webhook', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/webhook")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"eventType\": \"<string>\",\n \"url\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"webhookId": "<string>",
"eventType": "<string>",
"url": "<string>",
"status": 123,
"publicKey": "<string>"
}
}Use this endpoint to register a webhook URL that VelaFi will call when a specific event type occurs. Each registration is scoped to one event type, so create separate webhooks for each event you want to receive. A request is rejected while an active webhook already exists for that event type. Webhooks belong to your account, so one webhook receives its event for every merchant under the account. The response includes a
publicKey you must store — it is used to verify the RSA-SHA256 signature on all subsequent webhook deliveries for this endpoint.
All requests must include the
X-BH-TOKEN header and Content-Type: application/json. Store the publicKey from the response securely. It is also returned by List Webhooks.Endpoint
POST https://api.velafi.com/v2/webhook
Request Parameters
string
required
The event type this webhook should receive. Accepted values:
ORDER_WEBHOOK— fiat/crypto order status changesGLOBAL_PAYMENT_WEBHOOK— fiat/fiat global payment status changesFUNDING_WEBHOOK— Pending Fund account activityON_RAMP_WITHDRAW_WEBHOOK— the crypto withdrawal to the destination wallet of a completed API on-ramp order succeededSTABLE_COIN_PAYMENT_WEBHOOK— a stablecoin payment order was confirmedCRYPTO_WITHDRAW_WEBHOOK— a crypto withdrawal from a merchant wallet succeeded, failed, or was cancelled
string
required
The publicly accessible URL to which VelaFi will POST event notifications. It must start with
http. Use an https:// URL.Response Fields
number
HTTP-style response code.
200 indicates success.string
Human-readable status message, e.g.
SUCCESS.object
Show data fields
Show data fields
string
Unique identifier for this webhook registration.
string
The event type this webhook is registered for.
string
The callback URL registered.
number
Webhook status:
10 = active, 20 = disabled, 30 = deleted.string
Base64-encoded RSA public key used to verify the
signature header on incoming webhook requests. It is also returned by List Webhooks.Example
cURL
curl -X POST https://api.velafi.com/v2/webhook \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"eventType": "ORDER_WEBHOOK",
"url": "https://your-app.com/webhooks/velafi"
}'
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"webhookId": "ebab8a9663704e7cbbebe672c7c67912",
"eventType": "ORDER_WEBHOOK",
"url": "https://your-app.com/webhooks/velafi",
"status": 10,
"publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGz..."
}
}
If you lose the
publicKey, retrieve it with List Webhooks. See Webhook Setup for how to use the public key to verify incoming requests.Was this page helpful?
⌘I
Create a Webhook
curl --request POST \
--url https://api-test.velafi.com/v2/webhook \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"eventType": "<string>",
"url": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/webhook"
payload = {
"eventType": "<string>",
"url": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({eventType: '<string>', url: '<string>'})
};
fetch('https://api-test.velafi.com/v2/webhook', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/webhook")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"eventType\": \"<string>\",\n \"url\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"webhookId": "<string>",
"eventType": "<string>",
"url": "<string>",
"status": 123,
"publicKey": "<string>"
}
}