订阅管理

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

这可使您的内部工具保持同步，支持自动化工作流，并让团队即时掌握资金运营动态。

访问订阅

在侧边栏中导航至 开发者 > 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`	Key 注册进行中
`cobre_keys.status.registered`	Key 已注册
`cobre_keys.status.unregistered`	Key 已注销
`cobre_keys.status.disabled`	Key 已禁用
`cobre_keys.status.failed`	Key 注册失败

其他事件

事件键	触发条件
`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 安全性#

签名验证#

投递重试#

最佳实践#

故障排查#