可用事件类型
为您希望接收的每种事件类型分别注册一个 Webhook。如果某事件类型已存在有效的 Webhook,则创建新 Webhook 的请求将被拒绝;Webhook 会接收您账户下所有商户的对应事件。VelaFi 支持以下事件类型:ORDER_WEBHOOK
通过 API 创建的法币兑加密货币(入金)和加密货币兑法币(出金)订单发生状态变更时触发。
GLOBAL_PAYMENT_WEBHOOK
通过 API 创建的法币兑法币全球支付订单发生状态变更时触发。
FUNDING_WEBHOOK
商户法币(待处理资金 / Pending Fund)账户上的资金记录(法币充值、法币提现、购买加密货币或内部划转)完成、取消或退款时触发。加密货币钱包提现则由
CRYPTO_WITHDRAW_WEBHOOK 推送。ON_RAMP_WITHDRAW_WEBHOOK
VelaFi 已将已完成的 API 入金订单中的加密货币提现至订单目标钱包地址时触发。
STABLE_COIN_PAYMENT_WEBHOOK
稳定币支付订单确认时触发。
CRYPTO_WITHDRAW_WEBHOOK
商户钱包的加密货币提现成功、失败或被取消时触发。
注册 Webhook 端点
验证 Webhook 签名
VelaFi 发送到您端点的每个请求都包含signature 请求头。该值是对原始请求体的 RSA-SHA256 签名,以十六进制字符串编码。在处理负载之前,请务必验证此签名,以确保请求确实来自 VelaFi。
验证步骤如下:
- 从请求头中提取
signature值。 - 对
signature值进行十六进制解码。 - 使用 Webhook 注册响应中的
publicKey,将其作为针对原始请求体的 RSA-SHA256(SHA256withRSA,PKCS#1 v1.5)签名进行验证。 - 如果验证成功,处理负载并返回
{"callbackStatus": "SUCCESS"}。
- Java
- Python
- JavaScript
Webhook 负载结构
每种事件类型都会向您的端点发送不同的 JSON 请求体。ORDER_WEBHOOK — 入金和出金订单
ORDER_WEBHOOK — 入金和出金订单
GLOBAL_PAYMENT_WEBHOOK — 法币兑法币订单
GLOBAL_PAYMENT_WEBHOOK — 法币兑法币订单
FUNDING_WEBHOOK — 商户资金事件
FUNDING_WEBHOOK — 商户资金事件
当您商户法币(待处理资金 / Pending Fund)账户上的法币充值、法币提现、购买加密货币或内部划转完成、取消或退款时,VelaFi 会发送此负载。加密货币钱包提现则由
CRYPTO_WITHDRAW_WEBHOOK 推送。type 字段为 DEPOSIT、WITHDRAW、BUY_CRYPTO、TRANSFER_IN 或 TRANSFER_OUT 之一。status 字段为 2(已完成)、3(已取消)或 4(已退款)。处理中的记录不会被推送。确认接收
您的端点必须返回 HTTP2xx 响应(例如 200),并附带以下 JSON 请求体,以确认通知已成功接收和处理。如果 VelaFi 未收到 SUCCESS 确认(例如您的端点未在 6 秒内响应),将重试推送,总共尝试三次。有关重试时间表、重复处理和顺序,请参阅推送与重试。
在验证签名并持久化事件后,请立即返回
{"callbackStatus": "SUCCESS"}。任何下游处理都应异步执行,以避免因超时触发不必要的重试。
