Skip to main content
即刻安装 Cobo WaaS Skill，在 Claude Code、Cursor 等 AI 开发环境中使用自然语言集成 WaaS API，显著提升开发效率 🚀
TSS Node 在完成密钥生成（KeyGen）、密钥重分片（KeyReshare）、签名（KeySign）或分片签名（KeyShareSign）等操作时，可以将事件通知推送到您自己的服务器。节点以 HTTP POST 请求的形式发送到您配置的地址。 每条消息通过 JSON Web Token（JWT）承载，并使用 RS256 签名。您的接收服务器使用节点的 RSA 公钥验签，从而确认消息来自您的节点。
这些事件通知与 Cobo Webhook 事件不是同一套机制。Cobo Webhook 事件（wallets.mpc.tss_request.*）由 Cobo 平台发送到您在 Cobo Portal 注册的地址，并使用 Cobo 的 Webhook 签名。本页描述的事件由您自己部署的 TSS Node 发送，使用 request.* 事件名，由节点的 RSA 密钥签名，并在节点配置文件中配置。订阅其中一套不会收到另一套。关于 Cobo Webhook 事件，请参考 Webhook 事件类型。

​
开始之前

事件通知使用一对 RSA 2048 密钥。请在首次启动节点前生成密钥对并存入节点数据库：
公钥以 PEM 格式输出，请将其复制到接收服务器。

​
配置事件通知

在 TSS Node 配置文件（如 cobo-tss-node-config.yaml）中添加或取消注释 event 配置段：

​
顶层参数

​
服务器级参数

server 下的每个条目都继承顶层配置，并可覆盖其中任意一项。 以下示例将签名事件推送到一台服务器，并将全部事件推送到审计服务器，同时为审计服务器配置更长的重试预算：
同一事件可以推送给多台服务器。每台服务器独立维护重试状态，某一台失败不影响其他服务器的投递。

​
支持的事件类型

请只订阅您的集成会实际处理的事件类型，避免节点在您并不使用的事件上消耗投递次数。

​
KeyGen

​
KeySign

​
KeyReshare

​
KeyShareSign

​
请求格式

节点以表单编码的 POST 请求发送事件，JWT 放在 TSS_JWT_MSG 字段中：
JWT 使用 RS256 签名，签名私钥为节点本地存储的 RSA 2048 私钥。 JWT Header：
JWT Payload：
您的服务器必须返回 200 OK 或 201 Created。节点将其他状态码一律视为失败并重试。

​
事件结构

解码 package_data 后，事件体结构如下：
每个 data 对象都包含 data_type、request_id、request_type、request_status、request_detail、extra_info、failed_reason 和 result，其中 request_detail 与 result 内部的字段按操作类型不同。

​
投递与重试

某次投递失败后，节点等待 sleep_seconds 再重试，最多重试 retry_times 次。间隔固定，不会随重试次数增长。 以下行为对每台已配置的服务器都适用：
  • 将 retry_times 设为 0 表示无限重试，直到推送成功或节点停止。
  • 节点在首次尝试前将事件写入数据库，状态为 pending。节点重启后会恢复投递，最多恢复 1000 条待推送事件。
  • 推送成功后节点删除该事件记录；重试次数用尽后将该事件标记为 failed。
由于失败会重试，您的服务器可能重复收到同一事件，请按 event_id 去重。 下表说明两个重试参数如何配合：

​
健康检查

当 monitor_interval 非空时，节点会定期向每台事件服务器发送 ping 请求：
ping 请求使用与事件相同的 JWT 机制，其 package_data 中的 event_type 为 ping。ping 失败时节点最多重试 2 次，间隔 3 秒。 请将 ping 与业务事件分开处理：返回 200 OK 即可，无需其他处理。

​
实现接收服务器

Cobo 提供 Go 与 Java 两个事件服务器模板，您可以克隆后填入自己的业务逻辑： 两个模板的处理流程一致：
  1. 监听 POST /v2/event，从 TSS_JWT_MSG 表单字段中读取 JWT。
  2. 使用节点的 RSA 公钥（存放于 configs/tss-node-event-pub.key）验签，验签失败时返回 400 Bad Request。
  3. 从 package_data claim 中解码出事件 JSON。
  4. 使用 cobo-waas2 SDK 反序列化为 TSSEvent，再按事件类型分发处理。
  5. 处理成功返回 200 OK。ping 事件直接返回 200 OK，无需其他处理。
具体实现细节请参考仓库中各模板的 README.md 与源码。

​
推荐配置

以下配置可避免关键事件被丢弃，并将 token_expire_minutes 设得高于 request_timeout，使 token 不会在请求超时之前先过期：
节点在每次重试时都会重新生成 JWT，因此当 sleep_seconds 较大时，请相应提高 token_expire_minutes。

​
常见问题

在节点上运行 ./tss-node event key info，该命令以 PEM 格式输出公钥。将该公钥配置到接收服务器。
会。网络失败，或您的服务器未返回 200 OK 或 201 Created 时，节点会重试。请按 event_id（UUID）去重。
不会。节点在首次投递前会将事件以 pending 状态写入数据库，重启后恢复投递。
设为 0 表示无限重试；不配置则使用默认值 60。
建议设为 2 到 5 分钟，并保持高于 request_timeout，使 token 不会在请求超时之前先过期。当 sleep_seconds 较大时应进一步提高，因为节点在每次重试时都会重新生成 JWT。
可以。在 server 下为每台服务器添加一个条目，各服务器独立接收事件、独立重试。