Webhooks

概述
Webhooks 允许您在事件发生时接收实时通知，而无需轮询 API。这对于跟踪充值、提现和其他交易状态非常重要。

前提条件

在配置 Webhooks 之前，请确保您已完成以下步骤：

API 密钥

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

创建钱包

在控制面板中（参见创建主钱包）创建主钱包。

Webhook URL 端点

准备一个可公开访问的 HTTPS 端点来接收 Webhook 事件。

配置 Webhook URL

通过控制面板将您的 Webhook URL 添加到主钱包。

简介

通常，当您向 API 端点发出请求时，您期望获得近乎即时的响应。但是，某些请求可能需要较长时间处理，这可能导致超时错误。为了防止超时错误，会返回一个待处理响应。由于您的记录需要更新为请求的最终状态，您需要：

请求更新（通常称为轮询），或
使用 Webhook URL 监听事件。

实用提示
我们建议您使用 Webhook 为客户提供价值，而不是使用回调或轮询。使用回调时，我们无法控制客户端发生的情况。您也无法控制。如果客户设备上的网络连接失败或较弱，或者设备在交易后关闭，回调可能会失败。

轮询 vs Webhooks

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

	轮询	Webhooks
更新方式	手动	自动
速率限制	是	否
受扩展影响	是	否

创建 Webhook URL

Webhook URL 只是资源服务器发送更新的 POST 端点。该 URL 需要解析 JSON 请求并返回 200 OK：

// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    res.send(200);
});

<?php
// Retrieve the request's body and parse it as JSON
$input = file_get_contents("php://input");
$event = json_decode($input, true);

// Check for JSON parsing errors
if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400); // Bad Request
    echo json_encode(["error" => "Invalid JSON"]);
    exit();
}

// Do something with $event
// For example, log the event or process it
// log_event($event);

// Send a successful response
http_response_code(200); // HTTP status code 200 OK
echo json_encode(["status" => "success"]);
?>

当您的 Webhook URL 收到事件时，需要解析并确认事件。确认事件意味着在 HTTP 头中返回 200 OK。如果响应头中没有 200 OK，我们将在接下来的 2 小时 35 分钟内持续发送事件：

我们将尝试发送 5 次 Webhook，每次尝试之间的延迟递增，从 5 分钟开始并以指数方式增加到 80 分钟。这 5 次尝试的总持续时间约为 2 小时 35 分钟。

避免长时间运行的任务
如果您的 Webhook 函数中有长时间运行的任务，您应该在执行长时间运行的任务之前确认事件。长时间运行的任务会导致请求超时和服务器自动返回错误响应。没有 200 OK 响应，我们将按上述方式重试。

本地测试 Webhooks

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

重新发送交易 Webhook

如果由于某些原因您没有收到交易 Webhook 且退避时间已过，我们提供了一个 API 供您重新发送交易 Webhook

谨慎使用！
这可能导致处理已完成的交易，请确保在使用此端点时进行适当的验证。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/transactions/webhooks/resend \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "id": "TRANSACTION_ID"
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"id":"TRANSACTION_ID"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/transactions/webhooks/resend', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

验证事件来源

由于您的 Webhook URL 是公开可用的，您需要验证事件是否来自 Blockradar 而不是恶意攻击者。有两种方法可以确保 Webhook URL 的事件来自 Blockradar：

签名验证（推荐）

签名验证

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

const crypto = require('crypto');
const apiKey = process.env.WALLET_API_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('sha512', apiKey).update(JSON.stringify(req.body)).digest('hex');
    if (hash == req.headers['x-blockradar-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    }
    res.send(200);
});

<?php

// Retrieve the request's body
$body = file_get_contents('php://input');

// Get the API key from the environment
$apiKey = getenv('WALLET_API_KEY');

// Using HMAC-SHA512 for hashing
$signature = hash_hmac('sha512', $body, $apiKey);

// Check if the signature matches the one provided in the headers
if ($signature === $_SERVER['HTTP_X_BLOCKRADAR_SIGNATURE']) {
    // The signature is valid, proceed with processing the event
    $event = json_decode($body, true);
    // Do something with $event
}

// Send a 200 OK response
http_response_code(200);

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/my/webhook/url", methods=["POST"])
def webhook():
    # Retrieve the request's body
    body = request.get_data()

    # Get the API key
    api_key = os.environ.get('WALLET_API_KEY')

    # Using HMAC-SHA512 for hashing
    signature = hmac.new(api_key.encode('utf-8'), body, hashlib.sha512).hexdigest()

    # Check if the signature matches the one provided in the headers
    if signature == request.headers.get('X-BlockRadar-Signature'):
        # The signature is valid, proceed with processing the event
        event = json.loads(body.decode('utf-8'))
        # Do something with event

    # Send a 200 OK response
    return '', 200

上线检查清单

现在您已成功创建 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": {
  "amount": "0.000095597672027028",
  "symbol": "ETH",
  "amountUsd": "0.248568"
}

字段	说明
`amount`	以链的原生代币计的费用总额，为您的钱包在此交易流程中支付的所有费用之和
`symbol`	支付费用所用的原生代币，如 ETH、BNB、TRX、SOL 或 XLM
`amountUsd`	总额的美元价值。若任一组成部分无可用美元汇率则为 null，此时请对 `amount` 应用您自己的汇率

当事件不包含您的钱包支付的任何费用时，networkFee 为 null。最常见的情况是 deposit.success，其 gas 由存款人支付。该费用仍显示在交易的 gasFee 字段中，只是不是您承担的成本。

withdraw.failed 事件可能带有非 null 的 networkFee。如果提款在链上回滚，gas 仍然已被消耗。

networkFees

汇总背后可验证的明细。每一条都是一笔链上费用，带有自己的交易哈希，因此每一步都可以在区块浏览器上独立验证。一次逻辑操作通常涉及多笔费用交易，例如为存款地址充值 gas、批准代币，然后执行归集。下面的明细对应上面的 networkFee 汇总，其条目之和恰好等于该总额。

"networkFees": [
  {
    "operation": "GAS_FUNDING",
    "feeSource": "MASTER_WALLET",
    "status": "CONFIRMED",
    "txHash": "0x3f8d21c6a9b1e04f7c2d85e9410ab6c3d7f52e98014db67aa20c1e5f4b9d7e31",
    "feeNative": "0.000021",
    "feeUsd": "0.054603",
    "nativeRateUsd": "2600.15",
    "createdAt": "2024-10-23T11:28:31.204Z"
  },
  {
    "operation": "SWEEP",
    "feeSource": "MASTER_WALLET",
    "status": "CONFIRMED",
    "txHash": "0xe5ae1c025b81ff83a03189fad1c0f5bd502cd0b394bed6765603f9ba05bfe147",
    "feeNative": "0.000074597672027028",
    "feeUsd": "0.193965",
    "nativeRateUsd": "2600.15",
    "createdAt": "2024-10-23T11:28:52.901Z"
  }
]

字段	说明
`operation`	该费用的用途，如 `WITHDRAW`、`SWEEP`、`GAS_FUNDING`、`TOKEN_APPROVAL`、`DRAIN` 或 `ENERGY_PURCHASE`
`feeSource`	支付费用的钱包：`ADDRESS`（存款地址）、`MASTER_WALLET`（您的主钱包或资金池钱包）、`PLATFORM` 或 `PROVIDER`（由平台赞助，非您的成本）
`status`	费用状态，通常为 `CONFIRMED`
`txHash`	支付该费用的交易哈希
`feeNative`	以原生代币计的费用金额
`feeUsd`	记录时的美元价值，可能为 null
`nativeRateUsd`	该条目使用的原生代币兑美元汇率
`createdAt`	费用记录时间

使用这两个字段的两条规则：

向客户收费时请使用 networkFee。它只汇总您的钱包支付的条目（ADDRESS 和 MASTER_WALLET），并排除 Blockradar 赞助的部分（PLATFORM 和 PROVIDER）。切勿将赞助条目转嫁给您的客户。
明细是 webhook 发送时刻的快照。事件之后记录的费用（例如剩余 gas 的回收）会出现在 webhook 重发和网络费用 API（GET /wallets/{walletId}/network-fees）中，后者是实时账本。

事件示例

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

{
    "event": "deposit.success",
    "data": {
        "id": "6d2f9646-cae4-48a5-8bfe-1f9379868d4f",
        "reference": "LSk5RLfSrR",
        "senderAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
        "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
        "amount": "10.0",
        "amountPaid": "10.0",
        "fee": null,
        "currency": "USD",
        "blockNumber": 6928760,
        "blockHash": "0x5f2e0ed782752b9559e7a3d89c0fb9f6706e4866e74ba7a434cf933bb3f02a2b",
        "hash": "0x94c733496df59c15e5a489f20374096bba31166a8e149ceea4d410e3e5821357",
        "confirmations": 6,
        "confirmed": true,
        "gasPrice": "1201381238",
        "gasUsed": "62159",
        "gasFee": "0.000074676656372842",
        "status": "SUCCESS",
        "type": "DEPOSIT",
        "note": null,
        "amlScreening": {
            "provider": "ofac",
            "status": "success",
            "message": "Address is not sanctioned"
        },
        "network": "testnet",
        "chainId": 11155111,
        "metadata": {
            "user_id": 1
        },
        "createdAt": "2024-10-23T11:19:58.451Z",
        "updatedAt": "2024-10-23T11:19:58.451Z",
        "asset": {
            "id": "fe04a28c-c615-4e41-8eda-f84c862864f5",
            "name": "USDC Coin",
            "symbol": "USDC",
            "decimals": 6,
            "address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            "standard": "ERC20",
            "isActive": true,
            "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800083/crypto-assets/usd-coin-usdc-logo_fs9mhv.png",
            "network": "testnet",
            "createdAt": "2024-05-14T11:53:33.682Z",
            "updatedAt": "2024-06-14T22:32:12.589Z"
        },
        "address": {
            "id": "0a69c48a-6c6f-422c-bd6a-70de3306a3ac",
            "address": "0xe1037B45b48390285e5067424053fa35c478296b",
            "name": "Customer 1",
            "isActive": true,
            "type": "INTERNAL",
            "derivationPath": "m/44'/60'/0'/0/87",
            "metadata": {
                "user_id": 1
            },
            "network": "testnet",
            "createdAt": "2024-10-23T11:13:40.446Z",
            "updatedAt": "2024-10-23T11:13:40.446Z"
        },
        "blockchain": {
            "id": "85ffc132-3972-4c9e-99a5-5cf0ccb688bf",
            "name": "ethereum",
            "symbol": "eth",
            "slug": "ethereum",
            "derivationPath": "m/44'/60'/0'/0",
            "isEvmCompatible": true,
            "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800081/crypto-assets/ethereum-eth-logo_idraq2.png",
            "isActive": true,
            "tokenStandard": "ERC20",
            "createdAt": "2024-05-14T11:53:33.095Z",
            "updatedAt": "2024-06-14T22:32:11.983Z"
        },
        "wallet": {
            "id": "d236a191-c1d4-423c-a439-54ce6542ca41",
            "name": "Ethereum Master Wallet",
            "description": "This is ethereum testnet master wallet",
            "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
            "derivationPath": "m/44'/60'/0'/0/0",
            "isActive": true,
            "status": "ACTIVE",
            "network": "testnet",
            "createdAt": "2024-08-22T09:48:56.322Z",
            "updatedAt": "2024-10-23T10:52:34.332Z"
        },
        "beneficiary": null
    }
}

{
    "event": "deposit.processing",
    "data": {
        "id": "6d2f9646-cae4-48a5-8bfe-1f9379868d4f",
        "reference": "LSk5RLfSrR",
        "senderAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
        "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
        "amount": "10.0",
        "status": "PROCESSING",
        "type": "DEPOSIT",
        "network": "testnet"
    }
}

{
    "event": "withdraw.success",
    "data": {
        "id": "081d6315-159f-4c38-b02a-c4708836c5bd",
        "reference": "y8lvy55cK",
        "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
        "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
        "amount": "10",
        "amountPaid": "10",
        "status": "SUCCESS",
        "type": "WITHDRAW",
        "network": "testnet"
    }
}

{
    "event": "swap.success",
    "data": {
        "id": "99a2b490-0798-460b-9265-4d99f182fe52",
        "reference": "ZMxcorDGtf",
        "senderAddress": "0xAA2d5fd5e7bE97E214f8565DCf3a4862719960b5",
        "recipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
        "amount": "5",
        "status": "SUCCESS",
        "type": "SWAP",
        "toAmount": "4.965398",
        "rate": "0.9930796000000001",
        "network": "mainnet"
    }
}

{
    "event": "deposit.swept.success",
    "data": {
        "id": "6d2f9646-cae4-48a5-8bfe-1f9379868d4f",
        "reference": "LSk5RLfSrR",
        "amount": "10.0",
        "assetSwept": true,
        "assetSweptAt": "2024-10-23T11:28:52.848Z",
        "assetSweptGasFee": "0.000074597672027028",
        "assetSweptHash": "0xe5ae1c025b81ff83a03189fad1c0f5bd502cd0b394bed6765603f9ba05bfe147",
        "assetSweptSenderAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
        "assetSweptRecipientAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
        "assetSweptAmount": "10.0",
        "reason": "Funds swept successfully",
        "status": "SUCCESS",
        "type": "DEPOSIT",
        "network": "testnet"
    }
}

{
    "event": "withdraw.failed",
    "data": {
        "id": "081d6315-159f-4c38-b02a-c4708836c5bd",
        "reference": "y8lvy55cK",
        "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
        "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
        "amount": "10",
        "status": "FAILED",
        "type": "WITHDRAW",
        "network": "testnet"
    }
}

祝您开发愉快！

开始使用

钱包

收款

付款

转换与管理

合规与工具

前提条件

简介

轮询 vs Webhooks

创建 Webhook URL

本地测试 Webhooks

重新发送交易 Webhook

验证事件来源

签名验证

上线检查清单

事件类型

Webhook 载荷中的网络费用

networkFee

networkFees

事件示例

​前提条件

​简介

​轮询 vs Webhooks

​创建 Webhook URL

​本地测试 Webhooks

​重新发送交易 Webhook

​验证事件来源

​签名验证

​上线检查清单

​事件类型

​Webhook 载荷中的网络费用

​networkFee

​networkFees

​事件示例

前提条件

简介

轮询 vs Webhooks

创建 Webhook URL

本地测试 Webhooks

重新发送交易 Webhook

验证事件来源

签名验证

上线检查清单

事件类型

Webhook 载荷中的网络费用

networkFee

networkFees

事件示例