跳转到主要内容
概述
Webhooks 会在事件发生时——充值、提现、交换等——向您的服务器推送实时通知。您的服务器无需轮询 API,即可在交易完成时立即收到更新。

前提条件

在配置 Webhooks 之前,请确保您已具备:
1

API 密钥

从 Blockradar 控制面板 获取您的 API 密钥。导航至 Developers 生成密钥。
2

Webhook 端点

在您的服务器上创建一个 POST 端点,能够接收 JSON 载荷并返回 200 OK 响应。
3

HTTPS URL(生产环境)

在生产环境中,您的 Webhook URL 必须使用 HTTPS。本地测试时,可以使用 ngrok 或 webhook.site 等工具。
4

主钱包

通过控制面板在您的主钱包上配置 Webhook URL。

工作原理

当您向 API 端点发出请求时,您期望获得近乎即时的响应。但是,某些请求可能需要较长时间处理,这可能导致超时错误。为了防止超时错误,会返回一个待处理响应。由于您的记录需要更新为请求的最终状态,您需要:
  1. 请求更新(通常称为轮询),或
  2. 使用 Webhook URL 监听事件。
实用提示
我们建议您使用 Webhook 为客户提供价值,而不是使用回调或轮询。使用回调时,我们无法控制客户端发生的情况,您也无法控制。如果客户设备上的网络连接失败或较弱,或者设备在交易后关闭,回调可能会失败。

轮询 vs Webhooks

轮询需要定期发出 GET 请求以获取请求的最终状态。例如,当您为客户分配充值地址时,您需要不断请求与该地址关联的交易,直到找到一个。 使用 Webhooks,资源服务器(在本例中为 Blockradar)会在您请求的状态发生变化时向您的服务器发送更新。请求状态的变化称为事件。您通常会在称为 Webhook URL 的 POST 端点上监听这些事件。 下表突出显示了轮询和 Webhooks 之间的一些差异:

创建 Webhook URL

Webhook URL 只是资源服务器发送更新的 POST 端点。该 URL 需要解析 JSON 请求并返回 200 OK:
当您的 Webhook URL 收到事件时,需要解析并确认事件。确认事件意味着在 HTTP 头中返回 200 OK。如果响应头中没有 200 OK,我们将在接下来的 2 小时 35 分钟内持续发送事件:
  • 我们将尝试发送 5 次 Webhook,每次尝试之间的延迟递增,从 5 分钟开始并以指数方式增加到 80 分钟。这 5 次尝试的总持续时间约为 2 小时 35 分钟。
避免长时间运行的任务
如果您的 Webhook 函数中有长时间运行的任务,您应该在执行长时间运行的任务之前确认事件。长时间运行的任务会导致请求超时和服务器自动返回错误响应。没有 200 OK 响应,我们将按上述方式重试。

本地测试 Webhooks

在开发过程中,您可以在测试(TEST)主钱包环境中将 Webhook URL 配置为本地地址,例如 http://localhost 或 127.0.0.1。 要将本地服务器暴露到互联网以进行测试,请考虑使用 ngrok 或 webhook.site 等工具。这些工具允许您查看 Webhook 载荷的样子,并在将应用程序部署到正式环境之前在本地模拟 Webhook 事件。 使用这些工具,您可以确保 Webhook 集成正常工作,并在进入生产环境之前在受控的本地环境中处理任何问题。

重新发送交易 Webhook

如果由于某些原因您没有收到交易 Webhook 且退避时间已过,我们提供了一个 API 供您重新发送交易 Webhook。
谨慎使用!
这可能导致处理已完成的交易,请确保在使用此端点时进行适当的验证。

验证事件来源

由于您的 Webhook URL 是公开可用的,您需要验证事件是否来自 Blockradar 而不是恶意攻击者。有两种方法可以确保 Webhook URL 的事件来自 Blockradar:
  1. 签名验证(推荐)

签名验证

从 Blockradar 发送的事件带有 x-blockradar-signature 头。此头的值是使用您的密钥对事件载荷进行 HMAC SHA512 签名的结果。应在处理事件之前验证头签名:

上线检查清单

现在您已成功创建 Webhook URL,以下是确保您获得良好体验的一些方法:
  • 在 Blockradar 控制面板的主钱包上添加 Webhook URL
  • 确保您的 Webhook URL 是公开可用的(localhost URL 无法接收事件)
  • 如果使用 .htaccess,请记住在 URL 末尾添加尾部 /
  • 测试您的 Webhook,确保您能获取 JSON 主体并返回 200 OK HTTP 响应
  • 如果您的 Webhook 函数有长时间运行的任务,您应该首先通过返回 200 OK 确认收到 Webhook,然后再继续长时间运行的任务
  • 如果我们没有从您的 Webhook 收到 200 OK HTTP 响应,我们会将其标记为失败尝试
  • 我们将尝试发送 5 次 Webhook,每次尝试之间的延迟递增,从 5 分钟开始并以指数方式增加到 80 分钟。这 5 次尝试的总持续时间约为 2 小时 35 分钟。

事件类型

以下是我们目前触发的事件。随着我们在未来接入更多操作,我们会将更多事件添加到此列表中。

Webhook 载荷中的网络费用

每个交易 webhook 都包含两个描述交易处理过程中所产生网络费用的字段:networkFee 汇总和 networkFees 明细。

networkFee

您的 Blockradar 托管钱包在此交易流程中支付的网络费用总额,以链的原生代币和美元计。将成本转嫁给您的客户时,请使用该数值。
当事件不包含您的钱包支付的任何费用时,networkFee 为 null。最常见的情况是 deposit.success,其 gas 由充值方支付。该费用仍显示在交易的 gasFee 字段中,只是不是您承担的成本。
withdraw.failed 事件可能带有非 null 的 networkFee。如果提现在链上回滚,gas 仍然已被消耗。

networkFees

汇总背后可验证的明细。每一条都是一笔链上费用,带有自己的交易哈希,因此每一步都可以在区块浏览器上独立验证。一次逻辑操作通常涉及多笔费用交易,例如为充值地址注入 gas、批准代币,然后执行归集。下面的明细对应上面的 networkFee 汇总,其条目之和恰好等于该总额。
使用这两个字段的两条规则:
  1. 向客户收费时请使用 networkFee。它只汇总您的钱包支付的条目(ADDRESS 和 MASTER_WALLET),并排除 Blockradar 赞助的部分(PLATFORM 和 PROVIDER)。切勿将赞助条目转嫁给您的客户。
  2. 明细是 webhook 发送时刻的快照。事件之后记录的费用(例如剩余 gas 的回收)会出现在 webhook 重发和网络费用 API(GET /wallets/{walletId}/network-fees)中,后者是实时账本。

事件示例

以下是一些最常见事件的 Webhook 载荷示例:

法币入金交易 Webhooks

每当法币被兑换并结算为数字资产时,Blockradar 都会发出统一的交易 webhook。无论付款来自长期有效的虚拟账户,还是来自 Deposit Fiat 支付订单,均适用此规则。
Onramp Webhook
请使用 data.id 作为法币入金交易的标识符,并以幂等方式处理事件。来源关联字段标识了发起付款的通道:
  • 虚拟账户付款会填充 data.virtualAccount。
  • Deposit Fiat 支付订单会填充 data.paymentOrder。
Deposit Fiat 还可能额外发出 onramp.payment-order.* 事件,用于描述支付订单资源的生命周期。这些事件是对 onramp.* 的补充,并不会取代交易 webhook。请参见 Deposit Fiat webhooks。
deposit.* 事件仅用于交易类型为 DEPOSIT 的链上加密货币充值。法币兑换为加密货币的结算请使用 onramp.*,并以 onramp.success 确认完成。

完整事件列表

交易类型与状态

交易类型

Webhook 载荷中使用以下交易类型:

交易状态

以下状态表示交易的当前状态:
这些交易类型和状态用于 webhook 载荷的 type 和 status 字段,帮助您了解发生了哪类交易及其当前状态。
祝您开发愉快!❤️