La sección de Gestión de Suscripciones te permite configurar endpoints de webhook para recibir notificaciones en tiempo real sobre eventos en tu cuenta de Cobre. Cuando se completa un pago, cambia un saldo, o termina de procesarse un archivo masivo, Cobre envía los detalles directamente a tus sistemas—sin necesidad de consultas periódicas.Esto mantiene tus herramientas internas sincronizadas, habilita flujos de trabajo automatizados, y le da a tu equipo visibilidad instantánea sobre las operaciones de tesorería.
Acceso a Suscripciones#
Navega a Desarrolladores > Webhooks en la barra lateral. Verás la tabla de Suscripciones mostrando todas tus configuraciones de webhook activas.Visualización de tus Suscripciones#
La tabla de Suscripciones muestra:| Columna | Descripción |
|---|
| URL | El endpoint donde Cobre envía las notificaciones |
| Descripción | Tu etiqueta para identificar esta suscripción |
| ID | Identificador del sistema (formato: sub_XXXXXX) |
| Eventos | Cuántos tipos de evento monitorea esta suscripción |
| Fecha de creación | Cuándo se creó la suscripción |
La tabla muestra información de paginación (ej., "1-5 de 5") cuando tienes múltiples suscripciones.
Crear una Suscripción#
Haz clic en + Crear suscripción en la esquina superior derecha para abrir el formulario de creación.Campos Obligatorios#
URL del Webhook: El endpoint HTTPS que recibirá las notificaciones. Esta debe ser una URL públicamente accesible que controle tu servidor.Eventos: Selecciona qué tipos de evento quieres monitorear. Puedes elegir múltiples eventos para una sola suscripción—por ejemplo, suscribirte a todos los cambios de estado de movimientos de dinero con un solo endpoint.Campos Opcionales#
Descripción: Un nombre descriptivo para ayudarte a identificar la suscripción más tarde. Ejemplos: "Integración ERP," "Alertas de Pagos," "Sincronización Contable."Clave Secreta: Una contraseña (10-64 caracteres) utilizada para firmar las notificaciones. Cuando se proporciona, Cobre incluye una firma criptográfica con cada webhook para que puedas verificar la autenticidad. Guarda esta clave de forma segura—la necesitarás para validar las solicitudes entrantes.Después de completar el formulario, haz clic en Crear. Tu suscripción aparece en la tabla inmediatamente y comienza a recibir eventos.
Eventos Disponibles#
Saldo de Cuenta#
| Clave del Evento | Disparador |
|---|
accounts.balance.credit | Fondos recibidos en tu cuenta |
accounts.balance.debit | Fondos enviados desde tu cuenta |
Movimientos de Dinero#
| Clave del Evento | Disparador |
|---|
money_movements.status.initiated | Pago iniciado |
money_movements.status.processing | Pago en procesamiento |
money_movements.status.pending_approval | Pago esperando aprobación |
money_movements.status.completed | Pago completado |
money_movements.status.canceled | Pago cancelado |
money_movements.status.returned | Pago devuelto |
money_movements.status.rejected | Pago rechazado |
money_movements.status.failed | Pago fallido |
Movimientos de Dinero Transfronterizos#
| Clave del Evento | Disparador |
|---|
cross_border_money_movements.status.initiated | Transferencia internacional iniciada |
cross_border_money_movements.status.processing | Transferencia internacional en procesamiento |
cross_border_money_movements.status.completed | Transferencia internacional completada |
cross_border_money_movements.status.rejected | Transferencia internacional rechazada |
Movimientos de Dinero Masivos#
| Clave del Evento | Disparador |
|---|
bulk_money_movements.status.validating | Archivo masivo validando |
bulk_money_movements.status.processing | Pagos masivos en procesamiento |
bulk_money_movements.status.pending_approval | Archivo masivo esperando aprobación |
bulk_money_movements.status.completed | Procesamiento masivo completado |
bulk_money_movements.status.canceled | Archivo masivo cancelado |
bulk_money_movements.status.failed | Procesamiento masivo fallido |
Claves Cobre#
| Clave del Evento | Disparador |
|---|
cobre_keys.status.processing | Registro de clave en progreso |
cobre_keys.status.registered | Clave registrada |
cobre_keys.status.unregistered | Clave no registrada |
cobre_keys.status.disabled | Clave deshabilitada |
cobre_keys.status.failed | Registro de clave fallido |
Otros Eventos#
| Clave del Evento | Disparador |
|---|
reports.created | Reporte generado |
evidence-request.ask | Solicitud de evidencia creada |
Eliminar una Suscripción#
Pasa el cursor sobre cualquier fila de suscripción para mostrar la acción de eliminar. Eliminar una suscripción detiene todas las notificaciones a ese endpoint inmediatamente.Si necesitas cambiar eventos o la URL, elimina la suscripción existente y crea una nueva con la configuración actualizada.
Seguridad del Webhook#
Verificación de Firma#
Cuando incluyes una clave secreta durante la creación, cada notificación incluye dos headers:| Header | Contenido |
|---|
event-timestamp | Marca de tiempo UTC de la creación del evento |
event-signature | Hash HMAC SHA256 de 64 caracteres |
Para verificar una notificación:1.
Concatena la marca de tiempo y el cuerpo en bruto: {event-timestamp}.{body}
2.
Calcula HMAC-SHA256 usando tu clave secreta (codificación UTF-8)
3.
Compara tu resultado con el header event-signature
Reintentos de Entrega#
Cobre reintenta automáticamente las entregas fallidas:| Intento | Retraso |
|---|
| 1er reintento | 200ms |
| 2do reintento | 400ms |
| 3er reintento | 1000ms |
Los reintentos solo aplican a errores de conexión. Si tu endpoint devuelve un estado 4xx, Cobre no reintenta—así que siempre devuelve 2xx para una recepción exitosa.
Mejores Prácticas#
Usa endpoints HTTPS. HTTP no es compatible. Asegúrate de que tu URL de webhook use transmisión encriptada.Devuelve 2xx rápidamente. Confirma la recepción inmediatamente, luego procesa el evento de forma asíncrona. Tiempos de procesamiento largos arriesgan timeouts.Implementa idempotencia. Usa el id del evento para manejar posibles entregas duplicadas de forma elegante.Asegura tu clave secreta. Trátala como una contraseña. Si se ve comprometida, elimina la suscripción y crea una nueva.Suscríbete selectivamente. Comienza solo con los eventos que necesitas. Siempre puedes crear suscripciones adicionales más tarde.
Solución de Problemas#
¿No recibes notificaciones? Verifica que tu endpoint sea públicamente accesible, use HTTPS, y devuelva una respuesta 2xx.¿No coincide la firma? Verifica que estés usando el cuerpo en bruto (sin reformateo), el orden de concatenación correcto, y codificación UTF-8.¿Faltan eventos? Confirma que la suscripción incluye los tipos de evento que esperas. Revisa la columna de Eventos en la tabla. Modified at 2026-02-03 02:05:10
