监控地址到账通知

订阅的监控地址检测到代币转入时推送。

与 deposit.confirmed 的区别:

deposit.confirmed: 平台生成的用户充值地址到账，计入租户余额

watch.deposit.confirmed: 租户订阅的外部地址到账，仅通知不计余额

如果订阅时指定了 webhookUrl，推送到该 URL；否则推送到租户默认 callback_url。

通用规则（所有 webhook 共用）

出站请求 Header

Header	说明
`X-SIGNATURE`	Base64 RSA 签名，平台私钥对 `timestamp={X-TIMESTAMP}&body={raw body}` 做 SHA1WithRSA
`X-TIMESTAMP`	毫秒时间戳
`X-EVENT-TYPE`	事件类型（同 body 中 `eventType`）

商户用平台公钥验签即可。

ACK 规则

返回 HTTP 200 且 body 满足以下任一条件视为成功，否则触发重试：

JSON {"code": 0}

JSON {"success": true}

JSON {"status": "ok"}

纯文本 ok（不区分大小写）

重试策略

次数	间隔	累计
1	5 秒	5 秒
2	30 秒	35 秒
3	5 分钟	5 分 35 秒
4	30 分钟	35 分 35 秒
5	2 小时	2 小时 35 分
6	24 小时	26 小时 35 分

共 6 次重试（含首次共 7 次尝试），超过后不再重试。

回执签名（可选）

ACK body 可携带签名供平台验证：

{"code": 0, "timestamp": "<毫秒>", "signature": "<Base64>"}

签名原文：tenantId={tenantId}&timestamp={timestamp}&code={code}

算法：SHA1WithRSA，商户私钥签名，平台用商户公钥验证

timestamp 偏移容忍：5 分钟

验签失败不会触发重试，仅在审计日志（receipt_verified 字段）中标记

启用方式：联系平台运营注册商户 RSA-2048 公钥（Base64 X.509，不含 -----BEGIN PUBLIC KEY----- 头尾，
openssl rsa -in priv.pem -pubout -outform DER | base64 -w0 即可生成）

Fire-and-Forget 模式

联系运营把租户配置 webhookRequireAck=0，此模式下平台只推一次，不重试。

幂等性

每个事件携带唯一 eventId（UUID），商户应使用 eventId 做幂等去重。

Request

Header Params

Body Params application/jsonRequired

Example

{
    "eventId": "880e8400-e29b-41d4-a716-446655440003",
    "eventType": "watch.deposit.confirmed",
    "timestamp": 1777010700000,
    "tenantId": 1,
    "data": {
        "txHash": "0xabc...def",
        "network": "BNB",
        "currency": "USDT",
        "amount": "100.500000",
        "fromAddress": "0x123...456",
        "toAddress": "0xe835233c...",
        "watchAddressId": 1,
        "watchLabel": "交易所热钱包",
        "blockHeight": 94350000,
        "timestamp": 1777010700000
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

通用规则（所有 webhook 共用）#

出站请求 Header#

ACK 规则#

重试策略#

回执签名（可选）#

Fire-and-Forget 模式#

幂等性#