跳到导航
Agent Java SDK

Webhook 事件与强平预警

商户 Webhook 四类事件、幂等身份、强平预警字段和资金结果示例。

以 Markdown 格式查看

本文同步自 Agent Java SDK WEBHOOKS.md（提交 fa6c7b6）。本次仅更新文档，没有发布包含预警辅助方法的新 SDK 制品。

四类事件共用商户配置的一个回调地址（agents.webhook_url），按正文 event 分流；无需为预警单独配置 URL。下列均为结构示例，不用于向测试环境注入数据。

事件与幂等

event含义targetStatus / 去重键
transfer.completed划转终态，包括原单被冲正后的更新；不一定成功SUCCESS / FAILED / REVERSED；orderType:orderId:targetStatus
reverse.completed冲正订单终态SUCCESS / FAILED；orderType:orderId:targetStatus
transfer.dead重试仍无法确认资金订单最终状态，需要人工核对；不代表确定失败DEAD；orderType:orderId:targetStatus
liquidation.warning强平风险预警，无订单终态字段liquidation.warning:notificationId

商户预警 event 为 liquidation.warning，用户 WebSocket 的 data.event 仍为 LIQUIDATION_WARNING。不要混用两种通道。

兼容：历史商户通知曾使用 LIQUIDATION_WARNING。已冻结的发送正文及重试保持原样，接收端需同时识别两种名称。如果业务库原来使用大写前缀的预警键，必须继续使用原键或在迁移期查询两种键，避免再次处理。

本仓库当前 WebhookVerifier.idempotencyKey 只提取资金事件的 orderType:orderId:targetStatus，对预警正文会返回空串。 本次仅更新文档，没有发布包含预警辅助方法的新 SDK 制品。接收预警时，可继续使用现有 verify 方法验证原始正文签名；验签及归属校验通过后，在商户业务代码中识别上述两个事件名，校验 notificationId 为正整数十进制字符串，并构造 liquidation.warning:<notificationId>。不要把空串作为去重键，也不要要求预警具有资金订单字段。

去重必须在商户与 environment 范围内持久化，并与业务处理原子提交。不同 notificationId 的 FIRST/UPGRADE/REMINDER 都是独立通知；不要按用户、轮次或 eventType 合并丢弃。空幂等键表示无法提取有效身份，不能拿空串去重。SDK 只返回辅助键，不会保存或执行业务。相同身份不同正文应作为冲突记录，不覆盖已处理正文。

强平预警字段和示例

字段类型 / 说明
notificationId正整数十进制字符串，唯一通知 ID；不要转换为浮点数字
eventTypeFIRST：本轮首次；UPGRADE：本轮普通风险升级为高风险；REMINDER：持续风险再次提醒
severityNORMAL / HIGH。FIRST 可以直接为 HIGH；UPGRADE 对应 HIGH；REMINDER 可以为 NORMAL 或 HIGH
occurredAt数字，Unix 毫秒触发时间；不是 HTTP 接收时间
objecttype=CROSS 为全仓账户，symbol/side/positionId 为空串；ISOLATED 为逐仓仓位，携带对应合约、方向和仓位 ID
episode字符串，本轮预警轮次；FIRST 不是该用户历史第一次收到预警
stateVersion / configVersion字符串，上游状态版本 / 配置版本；不据此自行丢弃通知
riskRatio / minLargePositionValue / liquidationHighRiskThreshold十进制字符串，风险比率 / 普通预警阈值 / 高风险阈值，保留精度；阈值规则由上游计算
environmentPRODUCTION / SIMULATED，按配置环境隔离；不是服务器名称
agentId / agentCode / agentUserId字符串，代理 ID / 代理编码 / 商户侧用户 ID
platformUserId字符串，平台公开用户 ID，与绑定结果一致；不是服务内部 user_id
{
  "event": "liquidation.warning",
  "notificationId": "68460336",
  "eventType": "FIRST",
  "severity": "NORMAL",
  "occurredAt": 1791875870804,
  "object": {
    "type": "CROSS",
    "symbol": "",
    "side": "",
    "positionId": ""
  },
  "episode": "3",
  "stateVersion": "9",
  "riskRatio": "0.29133109",
  "minLargePositionValue": "0.20000000",
  "liquidationHighRiskThreshold": "0.40000000",
  "configVersion": "8",
  "environment": "PRODUCTION",
  "agentId": "16",
  "agentCode": "DEMO",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872"
}

资金划转结果示例

资金回调沿用既有类型：orderId 与 agentId 为 JSON 数字，amount 与 platformUserId 为字符串。不要套用预警的 agentId 字符串约定；读取大整数须使用无损整数/十进制类型。completedAt 为 UTC RFC3339，ts 为 Unix 秒。

{
  "environment": "PRODUCTION",
  "event": "transfer.completed",
  "orderType": "transfer",
  "orderId": 10001,
  "orderNo": "merchant-order-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

冲正结果示例

{
  "environment": "PRODUCTION",
  "event": "reverse.completed",
  "orderType": "transfer",
  "orderId": 10002,
  "orderNo": "merchant-reverse-001",
  "targetStatus": "SUCCESS",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

资金订单终止示例

{
  "environment": "PRODUCTION",
  "event": "transfer.dead",
  "orderType": "transfer",
  "orderId": 10003,
  "orderNo": "merchant-order-002",
  "targetStatus": "DEAD",
  "agentId": 16,
  "agentCode": "DEMO",
  "currency": "USDT",
  "amount": "10.00",
  "direction": "IN",
  "transferMode": "FIXED_AMOUNT",
  "agentUserId": "merchant-user-001",
  "platformUserId": "6054354872",
  "rejectCode": 0,
  "rejectMessage": "",
  "failReason": "order dead",
  "completedAt": "2026-10-13T07:17:50Z",
  "ts": 1791875870
}

上述示例仅展示协议；FAILED 的 rejectCode/rejectMessage/failReason 按实际拒绝结果返回，不能仅凭事件名判断资金已入账。

验签、响应与重试规则