通知与订阅

Cobre 的通知与订阅 API 提供了一种集中式机制，用于订阅平台事件并通过 Webhook 接收实时更新。该服务使客户能够及时了解跨多项功能（包括账户、资金流动、跨境操作、批量操作、报告、证据请求及 Cobre Keys）所发生的运营与财务变动。

通知采用标准化事件 Schema 进行推送，确保所有已订阅事件保持一致性。通过此 API，客户可订阅特定事件类型、管理其订阅，并可选择启用签名通知，以验证所接收事件的完整性与真实性。

创建订阅

订阅通过 创建订阅 API（POST /v1/subscriptions）创建。该接口端点允许客户指定：

希望订阅的事件

通知将被推送到的 目标 URL（Webhook）

用于内部参考的可选描述

用于启用签名通知的可选 event_signature_key

订阅创建完成后，每当已订阅事件发生时，Cobre 将开始推送 Webhook 通知。

可订阅事件目录

以下目录列出了 所有可订阅事件，按服务和功能分组。
创建订阅时请使用 Subscription Key。

Accounts Events

Cobre Keys Events

Counterparties Events

Money Movements Events

Bulk Money Movements Events

Cross-Border Money Movements Events

Evidence Requests Events

FX Rate Alerts Events

Reports Events

Account References Events

签名通知

签名通知通过允许客户验证所接收事件的真实性与完整性，提供额外一层安全保障。

如需启用签名通知，请在创建订阅时包含 event_signature_key 参数。

API 响应中返回的 event_signature_key 将被脱敏处理，仅最后 4 位字符可见。

签名通知请求头

event-timestamp：事件创建时间戳（UTC）

event-signature：使用事件载荷与签名密钥生成的 HMAC-SHA256 哈希值

验证通知签名

步骤一：拼接时间戳与请求体

event-timestamp + "." + raw_body

请求体必须 不含空格或换行符 发送。

正确拼接示例：

event-timestamp：2025-02-03T22:20:24Z

body：

{
   "id": "ev_BdES3CkhSVmz0rqGfWXs",
   "event_key": "accounts.balance.credit",
   "created_at": "2025-02-03T22:20:24Z",
   "content": {
     "id": "trx_SUrdrNG67vb8cztFdeA0",
     "type": "internal_credit",
     "amount": 1,
     "currency": "COP",
     "date": "2025-02-03T22:20:23.677Z",
     "metadata": {
       "uniqueTransactionId": "mm_9zPfIqJZAepjeR",
       "sender_account_number": "@coraa00233",
       "description": "BMM Unitary test",
       "sender_name": "Product Alpha",
       "tracking_key": "",
       "sender_id": "9011830296"
     },
     "account_id": "acc_rLR7UkxEt4",
     "previous_balance": 40460,
     "current_balance": 40461,
     "credit_debit_type": "credit"
   }
 }

拼接后的字符串：


2025-02-03T22:20:24Z.{"id":"ev_BdES3CkhSVmz0rqGfWXs","event_key":"accounts.balance.credit","created_at":"2025-02-03T22:20:24Z","content":{"id":"trx_SUrdrNG67vb8cztFdeA0","type":"internal_credit","amount":1,"currency":"COP","date":"2025-02-03T22:20:23.677Z","metadata":{"uniqueTransactionId":"mm_9zPfIqJZAepjeR","sender_account_number":"@coraa00233","description":"BMM Unitary test","sender_name":"Product Alpha","tracking_key":"","sender_id":"9011830296"},"account_id":"acc_rLR7UkxEt4","previous_balance":40460,"current_balance":40461,"credit_debit_type":"credit"}}

步骤 2：生成哈希值

算法：HMAC-SHA256

密钥：event_signature_key

编码：UTF-8

生成的哈希值必须与 event-signature 请求头中接收到的值一致。

正确哈希计算示例：

使用上述拼接字符串，并采用以下 event_signature_key 来复现哈希计算过程：

event_signature_key：


"cobre is super secure"

计算结果哈希值


1ff93b74902d1f94c38d0cf384a6b44d294b4557b3bfa8cb79c6dce9ba467215

请注意，计算所得的哈希值与 文档顶部请求头 event-signature 字段中发送的哈希值 完全一致。

在哈希计算过程中，您可能需要指定输入内容及 HMAC 的编码方式。在此类情况下，请使用 UTF-8 编码。

通知重试机制

重试次数	适用错误类型	触发条件	重试间隔
自动重试 3 次	仅限连接错误	4xx 响应不触发重试	200ms、400ms、1000ms