Notificaciones y Suscripciones

Las APIs de Notificaciones y Suscripciones de Cobre proporcionan un mecanismo centralizado para suscribirse a eventos de la plataforma y recibir actualizaciones en tiempo real a través de webhooks. Este servicio permite a los clientes mantenerse informados sobre cambios operacionales y financieros que ocurren en múltiples funcionalidades como Cuentas, Movimientos de Dinero, Operaciones Transfronterizas, Operaciones en Lote, Reportes, Solicitudes de Evidencia y Cobre Keys.

Las notificaciones se entregan utilizando un esquema de eventos estandarizado, asegurando consistencia en todos los eventos suscritos. A través de esta API, los clientes pueden suscribirse a tipos de eventos específicos, gestionar sus suscripciones y opcionalmente habilitar notificaciones firmadas para verificar la integridad y autenticidad de los eventos recibidos.

Creando Suscripciones

Las suscripciones se crean a través de la API Crear Suscripción (POST /v1/subscriptions). Este endpoint permite a los clientes especificar:

Los eventos a los que quieren suscribirse

La URL de destino donde se entregarán las notificaciones (webhook)

Una descripción opcional para referencia interna

Una event_signature_key opcional para habilitar notificaciones firmadas

Una vez que se crea una suscripción, Cobre comenzará a entregar notificaciones webhook cada vez que ocurra un evento suscrito.

Catálogo de Eventos Suscribibles

El siguiente catálogo lista todos los eventos disponibles a los que se puede suscribir, agrupados por servicio y funcionalidad.
Usa la Clave de Suscripción al crear una suscripción.

Eventos de Cuentas

Eventos de Cobre Keys

Eventos de Contrapartes

Eventos de Movimientos de Dinero

Eventos de Movimientos de Dinero en Lote

Eventos de Movimientos de Dinero Transfronterizos

Eventos de Solicitudes de Evidencia

Eventos de Reportes

Servicio	Tipo	Descripción	Clave de Suscripción	Layout
`accounts`	balance	Se activa cuando el saldo de una cuenta es acreditado	`accounts.balance.credit`	Account Transaction - credit
`accounts`	balance	Se activa cuando el saldo de una cuenta es debitado	`accounts.balance.debit`	Account Transaction - débito
`accounts`	created	evento que se activa cada vez que una nueva billetera es vinculada a una cuenta Cobre Balance Global	`accounts.linked_wallets.created`	Account Wallets

Notificaciones Firmadas

Las notificaciones firmadas proporcionan una capa adicional de seguridad al permitir que los clientes verifiquen la autenticidad e integridad de los eventos recibidos.

Para habilitar las notificaciones firmadas, incluye el parámetro event_signature_key al crear una suscripción.

La event_signature_key devuelta en la respuesta de la API será enmascarada. Solo los últimos 4 caracteres serán visibles.

Encabezados de Notificación Firmada

event-timestamp: Marca de tiempo de la creación del evento en UTC

event-signature: Hash HMAC-SHA256 generado usando el payload del evento y la clave de firma

Verificando Firmas de Notificación

Paso 1: Concatenar marca de tiempo y cuerpo

event-timestamp + "." + raw_body

El cuerpo debe ser enviado sin espacios o saltos de línea.

Ejemplo de concatenación correcta:

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

Cadena concatenada:


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

Paso 2: Generar el hash

Algoritmo: HMAC-SHA256

Clave: event_signature_key

Codificación: UTF-8

El hash generado debe coincidir con el valor recibido en el encabezado event-signature.

Ejemplo de cálculo correcto de hash:

Usando la cadena concatenada proporcionada anteriormente, usaremos la siguiente event_signature_key para replicar el cálculo del hash:

event_signature_key :


"cobre is super secure"

Hash resultante


1ff93b74902d1f94c38d0cf384a6b44d294b4557b3bfa8cb79c6dce9ba467215

Ten en cuenta que el hash calculado es el mismo que el enviado en el campo event-signature de los encabezados en la parte superior de la documentación.

En el proceso de cálculo del hash, puede que necesites especificar la codificación de entrada y HMAC. En estos casos, usa UTF-8.

Esquema de Reintentos de Notificación

Intentos de Reintento	Errores Aplicables	Condiciones	Intervalos de Reintento
3 reintentos automáticos	Solo errores de conexión	Sin reintentos para respuestas 4xx	200ms, 400ms, 1000ms

Acciones realizadas en Notificaciones y Suscripciones

🔑 Crear

🔍 Consulta

📋 Listar Eventos

❌ Eliminar

Descripción: Crear una suscripción a uno o más eventos y definir una URL de webhook.

Qué esperar después de la acción:
Un objeto Suscripción que incluye:

id

events

url

created_at

📘 Aprende más: 🔗 Crear una Suscripción

Esquema de Notificación Webhook

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

Cómo Empezar

Exponer un endpoint webhook seguro

Asegúrate de tener un endpoint HTTPS capaz de recibir solicitudes POST y manejar payloads JSON.

Identificar los eventos requeridos

Revisa el Catálogo de Eventos Suscribibles y selecciona todos los eventos relevantes.

Crear una suscripción

Registra tu URL de webhook y eventos seleccionados usando la API Crear Suscripción.

Implementar verificación de firma

Habilita notificaciones firmadas y valida eventos entrantes para asegurar autenticidad.

Manejar reintentos e idempotencia

Diseña tu lógica de webhook para procesar de forma segura eventos duplicados o reintentados.

Qué esperar después de usar esta API

Visibilidad operacional en tiempo real

Recibe actualizaciones en tiempo real a través de todas las funcionalidades de la plataforma suscritas.

Automatización basada en eventos

Activa flujos de trabajo internos como reconciliación, alertas y monitoreo.

Entrega confiable y segura

Las notificaciones firmadas y mecanismos de reintento aseguran la integridad de eventos y garantías de entrega.

Integraciones escalables

Construye arquitecturas escalables basadas en eventos sobre la plataforma de Cobre.

Notificaciones y Suscripciones

Creando Suscripciones#

Catálogo de Eventos Suscribibles#

Notificaciones Firmadas#

Encabezados de Notificación Firmada#

Verificando Firmas de Notificación#

Paso 1: Concatenar marca de tiempo y cuerpo#

Ejemplo de concatenación correcta:#

Cadena concatenada:#

Paso 2: Generar el hash#

Ejemplo de cálculo correcto de hash:#

Hash resultante#

Esquema de Reintentos de Notificación#

Acciones realizadas en Notificaciones y Suscripciones#

Esquema de Notificación Webhook#

Cómo Empezar#

Qué esperar después de usar esta API#

Creando Suscripciones

Catálogo de Eventos Suscribibles

Notificaciones Firmadas

Encabezados de Notificación Firmada

Verificando Firmas de Notificación

Paso 1: Concatenar marca de tiempo y cuerpo

Ejemplo de concatenación correcta:

Cadena concatenada:

Paso 2: Generar el hash

Ejemplo de cálculo correcto de hash:

Hash resultante

Esquema de Reintentos de Notificación

Acciones realizadas en Notificaciones y Suscripciones

Esquema de Notificación Webhook

Cómo Empezar

Qué esperar después de usar esta API