订阅管理

订阅管理模块允许您配置 Webhook 接口端点，以实时接收 Cobre 账户中各类事件的通知。当付款完成、余额发生变化或批量文件处理完毕时，Cobre 会将详细信息直接推送至您的系统——无需轮询。

这有助于保持您内部工具的数据同步，支持自动化工作流，并使您的团队能够即时掌握资金操作动态。

访问订阅管理

在侧边栏中导航至 Developers > Webhooks。您将看到订阅列表，其中显示所有已激活的 Webhook 配置。

查看订阅

订阅列表显示以下信息：

列名	说明
URL	Cobre 发送通知的接口端点地址
Description	您为该订阅设置的标识标签
ID	系统标识符（格式：sub_XXXXXX）
Events	该订阅所监听的事件类型数量
Creation date	订阅的创建时间

当您有多个订阅时，列表底部将显示分页信息（例如 "1-5 of 5"）。

创建订阅

点击右上角的 + Create subscription 按钮，打开创建表单。

必填字段

Webhook URL： 将接收通知的 HTTPS 接口端点地址。该地址必须是您服务器控制下的可公开访问的 URL。

Events： 选择您希望监听的事件类型。一个订阅可选择多个事件类型——例如，使用一个接口端点订阅所有资金流动状态变更。

可选字段

Description： 便于识别该订阅的友好名称。示例：「ERP 集成」、「付款提醒」、「财务同步」。

Secret Key： 用于对通知进行签名的密码短语（10 至 64 个字符）。配置后，Cobre 将在每条 Webhook 请求中附带加密签名，以便您验证其真实性。请妥善保存该密钥——您需要用它来验证传入的请求。

填写完表单后，点击 Create。您的订阅将立即出现在列表中，并开始接收事件。

可用事件

账户余额

事件键	触发条件
`accounts.balance.credit`	资金存入账户
`accounts.balance.debit`	资金从账户划出

资金流动

事件键	触发条件
`money_movements.status.initiated`	付款已发起
`money_movements.status.processing`	付款处理中
`money_movements.status.pending_approval`	付款待审批
`money_movements.status.completed`	付款已完成
`money_movements.status.canceled`	付款已取消
`money_movements.status.returned`	付款已退回
`money_movements.status.rejected`	付款已拒绝
`money_movements.status.failed`	付款失败

跨境资金流动

事件键	触发条件
`cross_border_money_movements.status.initiated`	跨境转账已发起
`cross_border_money_movements.status.processing`	跨境转账处理中
`cross_border_money_movements.status.completed`	跨境转账已完成
`cross_border_money_movements.status.rejected`	跨境转账已拒绝

批量资金流动

事件键	触发条件
`bulk_money_movements.status.validating`	批量文件校验中
`bulk_money_movements.status.processing`	批量付款处理中
`bulk_money_movements.status.pending_approval`	批量文件待审批
`bulk_money_movements.status.completed`	批量处理已完成
`bulk_money_movements.status.canceled`	批量文件已取消
`bulk_money_movements.status.failed`	批量处理失败

Cobre Keys

事件键	触发条件
`cobre_keys.status.processing`	密钥注册中
`cobre_keys.status.registered`	密钥已注册
`cobre_keys.status.unregistered`	密钥已注销
`cobre_keys.status.disabled`	密钥已禁用
`cobre_keys.status.failed`	密钥注册失败

其他事件

事件键	触发条件
`reports.created`	报告已生成
`evidence-request.ask`	证据请求已创建

删除订阅

将鼠标悬停在任意订阅行上，即可显示删除操作。删除订阅后，该接口端点将立即停止接收所有通知。

如需更改事件类型或 URL，请删除现有订阅，并使用更新后的配置创建新订阅。

Webhook 安全

签名验证

在创建订阅时配置密钥后，每条通知请求将包含以下两个请求头：

请求头	内容
`event-timestamp`	事件创建的 UTC 时间戳
`event-signature`	64 字符 SHA256 HMAC 哈希值

验证通知的步骤：

将时间戳与原始请求体拼接：{event-timestamp}.{body}

使用您的密钥（UTF-8 编码）计算 HMAC-SHA256

将计算结果与 event-signature 请求头进行比对

签名一致即可确认通知来源合法。

投递重试

Cobre 会自动重试失败的投递：

重试次数	延迟
第 1 次重试	200ms
第 2 次重试	400ms
第 3 次重试	1000ms

重试仅适用于连接错误。若您的接口端点返回 4xx 状态码，Cobre 将不再重试——因此，请务必在成功接收时返回 2xx 状态码。

最佳实践

使用 HTTPS 接口端点。 不支持 HTTP。请确保您的 Webhook URL 使用加密传输。

快速返回 2xx。 立即确认接收，然后异步处理事件。处理时间过长可能导致超时。

实现幂等性。 使用事件的 id 字段，优雅地处理可能出现的重复投递。

妥善保管密钥。 像对待密码一样保管它。若密钥泄露，请删除该订阅并创建新订阅。

按需订阅。 仅从您当前所需的事件类型开始订阅。您随时可以创建更多订阅。

故障排查

未收到通知？ 请确认您的接口端点可公开访问、使用 HTTPS，且能返回 2xx 响应。

签名不匹配？ 请确认您使用的是原始请求体（未经重新格式化），拼接顺序正确，且使用 UTF-8 编码。

事件缺失？ 请确认订阅中包含您期望的事件类型，并检查列表中的 Events 列。

订阅管理

访问订阅管理#

查看订阅#

创建订阅#

必填字段#

可选字段#

可用事件#

账户余额#

资金流动#

跨境资金流动#

批量资金流动#

Cobre Keys#

其他事件#

删除订阅#

Webhook 安全#

签名验证#

投递重试#

最佳实践#

故障排查#