Notifications & Subscriptions

Cobre’s Notifications & Subscriptions APIs provide a centralized mechanism to subscribe to platform events and receive real-time updates through webhooks. This service allows clients to stay informed about operational and financial changes occurring across multiple features such as Accounts, Money Movements, Cross-Border Operations, Bulk Operations, Reports, Evidence Requests, and Cobre Keys.

Notifications are delivered using a standardized event schema, ensuring consistency across all subscribed events. Through this API, clients can subscribe to specific event types, manage their subscriptions, and optionally enable signed notifications to verify the integrity and authenticity of received events.

Creating Subscriptions

Subscriptions are created through the Create Subscription API (POST /v1/subscriptions). This endpoint allows clients to specify:

The events they want to subscribe to

The destination URL where notifications will be delivered (webhook)

An optional description for internal reference

An optional event_signature_key to enable signed notifications

Once a subscription is created, Cobre will start delivering webhook notifications every time a subscribed event occurs.

Subscribable Events Catalog

The following catalog lists all available events that can be subscribed to, grouped by service and functionality.
Use the Subscription Key when creating a subscription.

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

Signed Notifications

Signed notifications provide an additional layer of security by allowing clients to verify the authenticity and integrity of received events.

To enable signed notifications, include the event_signature_key parameter when creating a subscription.

The event_signature_key returned in the API response will be masked. Only the last 4 characters will be visible.

Signed Notification Headers

event-timestamp: Timestamp of the event creation in UTC

event-signature: HMAC-SHA256 hash generated using the event payload and the signature key

Verifying Notification Signatures

Step 1: Concatenate timestamp and body

event-timestamp + "." + raw_body

The body must be sent without spaces or line breaks.

Example of correct concatenation:

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"
   }
 }

Concatenated string:


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"}}

Step 2: Generate the hash

Algorithm: HMAC-SHA256

Key: event_signature_key

Encoding: UTF-8

The generated hash must match the value received in the event-signature header.

Example of correct hash calculation:

Using the concatenated string provided earlier, we will use the following event_signature_key to replicate the hash calculation:

event_signature_key :


"cobre is super secure"

Resulting hash


1ff93b74902d1f94c38d0cf384a6b44d294b4557b3bfa8cb79c6dce9ba467215

Please note that the calculated hash is the same as the one sent in the event-signature field of the headers at the top of the documentation.

In the hash calculation process, you may need to specify the input and HMAC encoding. In these cases, use UTF-8.

Notification Retry Scheme

Retry Attempts	Applicable Errors	Conditions	Retry Intervals
3 automatic retries	Connection errors only	No retries for 4xx responses	200ms, 400ms, 1000ms

Webhook delivery is best-effort, not guaranteed. Retries are limited to the 3 attempts above (~1.6s total) and only cover connection errors — a 4xx response from your endpoint is not retried, and once the retry window ends the event is not queued for later redelivery.

If your endpoint is unavailable for longer than the retry window, or you suspect a missed event, do not rely on webhooks as the sole source of truth for critical state. Reconcile by polling the corresponding resource endpoint (e.g. the Money Movement, Account, or Transaction GET endpoint) to confirm current state.

Actions performed on Notifications & Subscriptions

🔑 Create

🔍 Retrieval

📋 List Events

❌ Delete

Description: Create a subscription to one or more events and define a webhook URL.

What to expect after the action:
A Subscription object including:

id

events

url

created_at

📘 Learn more: 🔗 Create a Subscription

Webhook Notification Schema

{
  "id": "ev_xxxxx",
  "event_key": "accounts.balance.credit",
  "created_at": "2025-02-03T22:20:24Z",
  "content": {
    // Event-specific payload
  }
}

How to Get Started

Expose a secure webhook endpoint

Ensure you have an HTTPS endpoint capable of receiving POST requests and handling JSON payloads.

Identify the required events

Review the Subscribable Events Catalog and select all relevant events.

Create a subscription

Implement signature verification

Enable signed notifications and validate incoming events to ensure authenticity.

Handle retries and idempotency

Design your webhook logic to safely process duplicate or retried events.

What to expect after using this API

Real-time operational visibility

Receive real-time updates across all subscribed platform features.

Event-driven automation

Trigger internal workflows such as reconciliation, alerts, and monitoring.

Reliable and secure delivery

Signed notifications and retry mechanisms ensure event integrity and delivery guarantees.

Scalable integrations

Build scalable event-driven architectures on top of Cobre’s platform.

Notifications & Subscriptions

Creating Subscriptions#

Subscribable Events Catalog#

Signed Notifications#

Signed Notification Headers#

Verifying Notification Signatures#

Step 1: Concatenate timestamp and body#

Example of correct concatenation:#

Concatenated string:#

Step 2: Generate the hash#

Example of correct hash calculation:#

Resulting hash#

Notification Retry Scheme#

Actions performed on Notifications & Subscriptions#

Webhook Notification Schema#

How to Get Started#

What to expect after using this API#

Creating Subscriptions

Subscribable Events Catalog

Signed Notifications

Signed Notification Headers

Verifying Notification Signatures

Step 1: Concatenate timestamp and body

Example of correct concatenation:

Concatenated string:

Step 2: Generate the hash

Example of correct hash calculation:

Resulting hash

Notification Retry Scheme

Actions performed on Notifications & Subscriptions

Webhook Notification Schema

How to Get Started

What to expect after using this API