跳转到内容

区块链支付 Webhook 的工作原理

Chaingateway 中的 Webhook 是一种订阅:当交易符合你设置的筛选条件时,例如有转账打入你的某个地址,我们的服务器就会向你的 URL 发送一个 HTTP POST 请求。这样你无需轮询,就能收到即时支付通知。Webhook 适用于 Ethereum、BNB Smart Chain、Polygon、Arbitrum、TRON 和 Bitcoin,不适用于 Solana。

Webhook 的生命周期:用筛选条件创建 Webhook,匹配的交易触发对你 URL 的 POST,你的服务器返回 200,投递失败的通知会被列出并按需重新发送 创建 Webhook POST /api/v2/{chain}/webhooks,带 url 和筛选条件 有交易匹配筛选条件 Chaingateway 把通知 POST 到你的 url 你的接收端返回 200 并处理 payload 投递失败? GET .../webhooks/notifications/failed,再 POST .../notifications/{id}/retry
失败的通知不会自动重试。你需要自己列出并重新发送它们。

你提供一个公开的 URL 和一个筛选条件,Chaingateway 会针对每笔匹配的交易调用一次该 URL。该调用是带 JSON 请求体的 HTTP POST。你的应用读取请求体并据此行动,例如把订单标记为已支付。用于支付时,这种模式也叫 Instant Payment Notification,简称 IPN。

请在预期付款到来之前不久,用将收款的地址创建 Webhook。每条通知都带有下面的数据。type 是资产类型,这里是一笔 TRC20 代币转账。

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

创建 Webhook 之前我需要准备什么?

Section titled “创建 Webhook 之前我需要准备什么?”

你需要一个接收端,也就是你服务器上能接受来自互联网的 POST 请求的端点。整个流程分四步:

  1. 构建一个 Chaingateway 能够访问的接收端点。
  2. 创建一个指向该接收端的 Webhook。
  3. 等待匹配的区块链事件。
  4. 读取请求体,并返回 HTTP 状态码 200。

接收端必须可以公开访问。请检查防火墙、反向代理和网络规则,因为私有地址或被封锁的端口会导致每次投递都失败。如果你设置了个人密钥,请在信任每个请求之前先校验它的签名,详见 Webhook 安全。下面的接收端只读取请求体并返回响应。

from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook_receiver():
data = request.get_json()
# Process the webhook data
# Update database, trigger notifications, execute business logic, etc.
return 'Webhook received successfully', 200
if __name__ == '__main__':
app.run()

向 /api/v2/{chain}/webhooks 发送 POST 请求。请求体需要包含你的接收端的 url 和一个筛选条件。筛选字段如下。

字段含义
url必填。接收端的完整 URL,包括路径。
from要监控的发送方地址。
to要监控的接收方地址。
contractaddress你想追踪的代币的合约地址。Bitcoin 上不可用。
token_idNFT 代币 id。
type资产类型。Ethereum 和 Arbitrum:ETH、ERC20、ERC721。Polygon:MATIC、ERC20、ERC721。BNB Smart Chain:BNB、BEP20、BEP721。TRON:TRX、TRC10、TRC20、TRC721。
reference你自己的标签,最长 255 个字符。

请提供 from 或 to。如果两者都不提供,API 要求提供 contractaddress 和 token_id。Bitcoin 的 Webhook 只接受 url、from 和 to。地址格式会被校验,不匹配的地址会返回状态码 422,并在 errors 中给出字段名。

Terminal window
curl --request POST \
--url https://app.chaingateway.io/api/v2/ethereum/webhooks \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
"url": "https://example.com/webhook",
"contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"type": "ERC20",
"reference": "order-1042"
}'

成功的调用返回状态码 201 和 Webhook 的 id:

{
"status": 201,
"ok": true,
"message": "Webhook created",
"data": {
"webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46"
}
}

你可以这样管理现有的 Webhook:用 GET /api/v2/{chain}/webhooks 列出,用 GET .../webhooks/{id} 读取单个,用 PUT .../webhooks/{id} 修改,用 DELETE .../webhooks/{id} 删除。付款到账后请删除该 Webhook,这样它就不会继续匹配之后的转账。当 id 不存在时,PUT 会返回状态码 404 和消息 Webhook not found。

Chaingateway 不会自行重试失败的投递。失败的通知会被保存下来,你需要自己读取并重新发送。相关的两个端点是 GET /api/v2/{chain}/webhooks/notifications/failed 和 POST /api/v2/{chain}/webhooks/notifications/{id}/retry。列表通过 page 查询参数分页。

每个条目显示 txid、目标 url、你的服务器已保存的 response 以及 attempts 次数。启动重试后,该通知会从失败列表中移除。如果重试也失败,它会回到列表中。GET /api/v2/{chain}/webhooks/notifications 会列出所有通知,包括成功的。请运行一个小任务,定期检查失败列表并重试其中的通知,同时让接收端具备幂等性,以 txid 作为键,这样重复的通知也不会造成影响。

Solana 没有 Webhook 端点。OpenAPI 文件只为 Ethereum、BNB Smart Chain、Polygon、Arbitrum、TRON 和 Bitcoin 定义了它们。对于 Solana,请定期读取收款地址的余额或列出交易,并把结果与你的记录对比。