跳转到主要内容
Webhook 让 VelaFi 能够在重要事件发生时立即向您的服务器推送实时通知——例如订单状态变更、资金到账,或全球支付在其生命周期中流转。您无需反复轮询 API,只需注册一次 HTTPS 端点,每当订阅的事件触发时,VelaFi 就会向该端点发送带有 JSON 负载的 HTTP POST 请求。本指南介绍如何注册端点、验证请求签名以及确认接收。
Webhook 不会在沙盒环境中触发(https://api-test.velafi.com)。请在本地模拟负载来测试 Webhook 处理逻辑,然后在生产环境中使用小额交易进行端到端验证。

可用事件类型

为您希望接收的每种事件类型分别注册一个 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。 验证步骤如下:
  1. 从请求头中提取 signature 值。
  2. 对 signature 值进行十六进制解码。
  3. 使用 Webhook 注册响应中的 publicKey,将其作为针对原始请求体的 RSA-SHA256(SHA256withRSA,PKCS#1 v1.5)签名进行验证。
  4. 如果验证成功,处理负载并返回 {"callbackStatus": "SUCCESS"}。

Webhook 负载结构

每种事件类型都会向您的端点发送不同的 JSON 请求体。
通过 API 创建的法币兑加密货币和加密货币兑法币订单发生状态变更时,VelaFi 会发送此负载。以下为简化示例;完整字段请参阅订单事件。
入金订单的 orderType 为 BUY,出金订单为 SELL。仅部分状态会被推送,被拒绝或超时的订单以 70 推送。推送的状态请参阅订单事件。
通过 API 创建的法币兑法币全球支付订单发生状态变更时,VelaFi 会发送此负载。
orderStatus 使用与全球支付订单详情端点相同的状态码,但仅推送全球支付事件中列出的状态。
当您商户法币(待处理资金 / Pending Fund)账户上的法币充值、法币提现、购买加密货币或内部划转完成、取消或退款时,VelaFi 会发送此负载。加密货币钱包提现则由 CRYPTO_WITHDRAW_WEBHOOK 推送。
type 字段为 DEPOSIT、WITHDRAW、BUY_CRYPTO、TRANSFER_IN 或 TRANSFER_OUT 之一。status 字段为 2(已完成)、3(已取消)或 4(已退款)。处理中的记录不会被推送。

确认接收

您的端点必须返回 HTTP 2xx 响应(例如 200),并附带以下 JSON 请求体,以确认通知已成功接收和处理。如果 VelaFi 未收到 SUCCESS 确认(例如您的端点未在 6 秒内响应),将重试推送,总共尝试三次。有关重试时间表、重复处理和顺序,请参阅推送与重试。
在验证签名并持久化事件后,请立即返回 {"callbackStatus": "SUCCESS"}。任何下游处理都应异步执行,以避免因超时触发不必要的重试。