Notificaciones y Suscripciones
Creando Suscripciones
POST /v1/subscriptions). Este endpoint permite a los clientes especificar:Catálogo de Eventos Suscribibles
Usa la Clave de Suscripción al crear una suscripción.
Notificaciones Firmadas
event_signature_key al crear una suscripción.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 UTCevent-signature: Hash HMAC-SHA256 generado usando el payload del evento y la clave de firmaVerificando Firmas de Notificación
Paso 1: Concatenar marca de tiempo y cuerpo
event-timestamp + "." + raw_bodyEjemplo de concatenación correcta:
event-timestamp: 2025-02-03T22:20:24Zbody:{
"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
event_signature_keyevent-signature.Ejemplo de cálculo correcto de hash:
event_signature_key para replicar el cálculo del hash:event_signature_key :
"cobre is super secure"
Hash resultante
1ff93b74902d1f94c38d0cf384a6b44d294b4557b3bfa8cb79c6dce9ba467215
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 |
4xx de tu endpoint no se reintenta, y una vez finalizada la ventana de reintentos el evento no queda en cola para una entrega posterior.GET de Movimiento de Dinero, Cuenta o Transacción) para confirmar el estado actual.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: 📘 Aprende más: 🔗 Crear una Suscripción
Un objeto Suscripción que incluye:
ideventsurlcreated_atEsquema 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.
Modified at 2026-08-20 21:26:54