Saltar a contenido

Integraciones: API Keys y Webhooks

Rubriq permite la integración con sistemas externos (ERP, CRM, plataformas propias) mediante dos mecanismos: API Keys para acceso programático y Webhooks para recibir notificaciones de eventos en tiempo real.

Acceder

  • Menú lateral → Configuraciones → pestaña Integraciones.
  • O directamente desde el menú Admin.
  • Ruta: /configuraciones (pestaña Integraciones)

API Keys

Las API Keys permiten que sistemas externos se comuniquen con la API pública de Rubriq para crear trámites de firma, consultar estados y descargar documentos firmados.

Crear una API Key

  1. En la sección API Keys, haz clic en Crear API Key.
  2. Ingresa un nombre descriptivo para la integración (ej: "ERP Contable", "CRM Ventas").
  3. Haz clic en Crear.
  4. Se genera la key con formato sk_live_XXXXXXXXXXXXXX.

⚠️ La key completa se muestra una sola vez. Cópiala y guárdala en un lugar seguro inmediatamente. Después de cerrar el diálogo, solo verás el prefijo (los primeros caracteres).

Seguridad de las API Keys

  • La key completa nunca se almacena en texto plano en la base de datos.
  • Se almacena un hash SHA-256 de la key para verificación.
  • Solo el prefijo (primeros 10 caracteres) se almacena para identificación visual.
  • Las keys no tienen fecha de expiración — se mantienen activas hasta que las elimines.

Eliminar una API Key

  1. Haz clic en el ícono de eliminar junto a la key.
  2. Confirma la eliminación.

La eliminación es inmediata e irreversible. Cualquier sistema que use esa key dejará de tener acceso a la API.

Modo Sandbox

Al crear una API Key, puedes activar el modo sandbox:

  • Las keys sandbox no envían correos electrónicos reales a los firmantes.
  • Los trámites creados en sandbox se auto-firman automáticamente después de unos segundos.
  • Ideal para desarrollo y pruebas de integración.

Usar la API Key

Los sistemas externos deben enviar la API Key en el encabezado X-API-Key de cada petición:

X-API-Key: sk_live_XXXXXXXXXXXXXX

Para documentación completa de los endpoints disponibles, consulta la documentación OpenAPI en /api/v1/docs/ de tu instancia de Rubriq.

Webhooks

Los webhooks permiten que Rubriq notifique a tu sistema cuando ocurren eventos importantes, enviando una petición HTTP POST a una URL que tú configuras.

Crear un webhook

  1. En la sección Webhooks, haz clic en Crear Webhook.
  2. Ingresa la URL de destino (ej: https://mi-sistema.com/webhooks/rubriq).
  3. Selecciona los eventos que quieres recibir.
  4. Haz clic en Crear.

Rubriq genera automáticamente un secret HMAC para firmar las entregas. Este secret se usa para verificar que las peticiones provienen de Rubriq.

Eventos disponibles

Evento Se dispara cuando...
document.created Se crea un nuevo trámite de firma.
document.signed Un firmante firma exitosamente un documento.
document.rejected Un firmante rechaza firmar un documento.
document.completed Todos los firmantes han firmado (trámite completado).
document.expired El plazo de firma vence sin completar todas las firmas.
document.cancelled El creador cancela manualmente el trámite.
document.reminder_sent Se envía un recordatorio automático a firmantes pendientes.

Verificación HMAC

Cada entrega incluye un encabezado X-Rubriq-Signature con la firma HMAC-SHA256 del payload:

X-Rubriq-Signature: sha256=<hex>

Tu sistema debe verificar esta firma comparándola con el HMAC calculado usando el secret compartido y el cuerpo de la petición.

Reintentos automáticos

Si tu endpoint responde con un código de error (5xx o timeout), Rubriq reintenta la entrega automáticamente con backoff exponencial:

  • Intento 1: inmediato.
  • Intento 2: después de unos minutos.
  • Intento 3: después de más tiempo.

Desactivación automática

Si un webhook acumula 5 secuencias de entrega fallidas consecutivas (todos los reintentos agotados), el endpoint se desactiva automáticamente para evitar carga innecesaria.

Para reactivar un webhook desactivado: 1. Haz clic en Reactivar junto al webhook. 2. El contador de fallos se reinicia a 0.

Historial de entregas

Para cada webhook puedes ver el historial de entregas:

  1. Haz clic en el webhook para expandir sus detalles.
  2. Selecciona Ver entregas.
  3. Se muestra una lista con cada intento de entrega:
Campo Descripción
Evento Tipo de evento (document.signed, etc.).
Intento Número de intento (1, 2, 3...).
HTTP Status Código de respuesta de tu servidor.
Éxito Si la entrega fue exitosa.
Duración Tiempo de respuesta en milisegundos.
Fecha Fecha y hora del intento.

Reintentar una entrega

Si una entrega falló y quieres reenviarla manualmente:

  1. Ve al historial de entregas del webhook.
  2. Haz clic en Reintentar.
  3. Rubriq reenviará la última entrega fallida a tu endpoint.

Eliminar un webhook

  1. Haz clic en el ícono de eliminar junto al webhook.
  2. Confirma la eliminación.

Trámites API

Acceder

  • Menú lateral → Trámites API (sección Admin).
  • Ruta: /admin/api-workflows

Descripción

Esta página muestra los trámites de firma que fueron creados a través de la API pública (usando API Keys), a diferencia de los creados manualmente desde la interfaz web.

Incluye:

  • Título del trámite.
  • Estado (En progreso, Completado, etc.).
  • Fecha de creación.
  • Búsqueda por título.
  • Paginación para listas extensas.

Los administradores ven todos los trámites API de su organización. Los superadministradores ven los de todas las organizaciones.

Esta vista es útil para monitorear que las integraciones externas estén funcionando correctamente y los trámites se estén creando como se espera.