> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # Webhook 事件与强平预警 本文同步自 [Agent Java SDK `WEBHOOKS.md`](https://github.com/6mm-com/agent-java-sdk/blob/fa6c7b65124f1346f815b3b73eb8a7729466c3dc/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:`。不要把空串作为去重键，也不要要求预警具有资金订单字段。 去重必须在商户与 environment 范围内持久化，并与业务处理原子提交。不同 notificationId 的 FIRST/UPGRADE/REMINDER 都是独立通知；不要按用户、轮次或 eventType 合并丢弃。空幂等键表示无法提取有效身份，不能拿空串去重。SDK 只返回辅助键，不会保存或执行业务。相同身份不同正文应作为冲突记录，不覆盖已处理正文。 ## 强平预警字段和示例 | 字段 | 类型 / 说明 | | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | | notificationId | 正整数十进制字符串，唯一通知 ID；不要转换为浮点数字 | | eventType | FIRST：本轮首次；UPGRADE：本轮普通风险升级为高风险；REMINDER：持续风险再次提醒 | | severity | NORMAL / HIGH。FIRST 可以直接为 HIGH；UPGRADE 对应 HIGH；REMINDER 可以为 NORMAL 或 HIGH | | occurredAt | 数字，Unix 毫秒触发时间；不是 HTTP 接收时间 | | object | type=CROSS 为全仓账户，symbol/side/positionId 为空串；ISOLATED 为逐仓仓位，携带对应合约、方向和仓位 ID | | episode | 字符串，本轮预警轮次；FIRST 不是该用户历史第一次收到预警 | | stateVersion / configVersion | 字符串，上游状态版本 / 配置版本；不据此自行丢弃通知 | | riskRatio / minLargePositionValue / liquidationHighRiskThreshold | 十进制字符串，风险比率 / 普通预警阈值 / 高风险阈值，保留精度；阈值规则由上游计算 | | environment | PRODUCTION / SIMULATED，按配置环境隔离；不是服务器名称 | | agentId / agentCode / agentUserId | 字符串，代理 ID / 代理编码 / 商户侧用户 ID | | platformUserId | 字符串，平台公开用户 ID，与绑定结果一致；不是服务内部 user_id | ```json { "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 秒。 ```json { "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 } ``` ## 冲正结果示例 ```json { "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 } ``` ## 资金订单终止示例 ```json { "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 按实际拒绝结果返回，不能仅凭事件名判断资金已入账。 [验签、响应与重试规则](/zh-CN/sdk/security/webhooks-idempotency)