Skip to main content

​
¿Qué son los Webhooks?

Los webhooks te permiten recibir notificaciones HTTP en tiempo real cuando ocurren eventos en tu organización de Gu1. En lugar de consultar la API repetidamente, Gu1 envía solicitudes POST automáticas a tu endpoint configurado cada vez que sucede algo importante.

​
¿Por qué Usar Webhooks?

Actualizaciones en Tiempo Real

Recibe notificaciones instantáneas cuando ocurren eventos

Eficiente

No es necesario consultar la API repetidamente

Flujos de Trabajo Automatizados

Activa acciones automáticamente basadas en eventos

Escalable

Maneja grandes volúmenes sin impacto en el rendimiento

​
Cómo Funcionan los Webhooks

  1. Configura un webhook en tu dashboard de Gu1
  2. Suscríbete a tipos de eventos específicos
  3. Recibe solicitudes HTTP POST cuando ocurren eventos
  4. Procesa eventos en tu aplicación

​
Tipos de Eventos Disponibles

Gu1 admite webhooks para las siguientes categorías:

​
Eventos de Entidades

Rastrea cambios en personas, empresas y otras entidades:
  • entity.created - Nueva entidad creada
  • entity.updated - Datos de entidad actualizados
  • entity.status_changed - Estado de entidad modificado
  • entity.deleted - Entidad eliminada (próximamente)
Más información sobre Eventos de Entidades →

​
Eventos de KYC

Monitorea procesos de verificación de identidad:
  • kyc.validation_created - Validación de KYC iniciada
  • kyc.validation_in_progress - Usuario comenzó la verificación
  • kyc.validation_approved - Verificación aprobada
  • kyc.validation_rejected - Verificación fallida
  • kyc.validation_abandoned - Usuario abandonó el proceso
  • kyc.validation_expired - Sesión de validación expirada
Más información sobre Eventos de KYC →

​
Eventos de Reglas

Rastrea ejecuciones de cumplimiento y reglas de negocio:
  • rule.triggered - Regla coincidió y se ejecutó
Más información sobre Eventos de Reglas →

​
Eventos de Transacciones (Próximamente)

Monitorea actividad de transacciones:
  • transaction.created - Nueva transacción registrada
  • transaction.updated - Transacción actualizada
  • transaction.flagged - Transacción marcada como sospechosa

​
Eventos de Alertas (Próximamente)

Rastrea investigaciones y alertas:
  • alert.created - Nueva alerta creada
  • alert.resolved - Alerta resuelta
  • alert.status_changed - Estado de alerta modificado

​
Características Clave

​
Configuración a Nivel de Organización

Los webhooks se configuran a nivel de organización, no por solicitud. Una configuración aplica a todos los eventos coincidentes en tu organización.

​
Soporte de Ambientes

Crea webhooks separados para diferentes ambientes:
  • Sandbox - Para pruebas y desarrollo
  • Production - Para operaciones en vivo

​
Filtrado Avanzado

Filtra qué eventos activan webhooks:
  • Tipos de entidades - Solo personas, solo empresas, etc.
  • Cambios de estado - Solo cuando cambia desde/hacia estados específicos
  • Filtros personalizados - Criterios adicionales basados en datos de eventos

​
Seguridad

  • Firmas HMAC SHA-256 - Verifica que las solicitudes provienen de Gu1
  • HTTPS requerido - Todos los webhooks deben usar endpoints seguros
  • Rotación de secretos - Regenera secretos en cualquier momento

​
Confiabilidad

  • Reintentos automáticos - Las solicitudes fallidas se reintentan con retroceso exponencial
  • Política de reintentos configurable - Personaliza el comportamiento de reintentos por webhook
  • Registros de entrega - Rastrea todos los intentos de entrega y respuestas

​
Monitoreo

  • Historial de ejecución - Ve todas las entregas de webhooks
  • Estadísticas - Tasas de éxito/fallo y tiempos
  • Seguimiento de errores - Mensajes de error detallados para depuración

​
Inicio Rápido

Comienza con webhooks en 3 pasos:
1

Configurar Webhook

Ve a Configuración → Webhooks y crea un nuevo webhook con la URL de tu endpoint.Guía de Configuración →
2

Suscribirse a Eventos

Selecciona qué tipos de eventos deseas recibir (ej., entity.*, kyc.*).
3

Implementar Endpoint

Crea un endpoint HTTPS que reciba solicitudes POST y verifique firmas.Guía de Seguridad →

​
Casos de Uso Comunes

Escenario: Activar automáticamente cuentas de clientes cuando se aprueba el KYC.Eventos: kyc.validation_approvedAcciones:
  • Actualizar estado del cliente en tu base de datos
  • Enviar correo de bienvenida
  • Habilitar funciones de cuenta
  • Notificar a equipos internos
Escenario: Rastrear cambios de estado de entidades para informes de cumplimiento.Eventos: entity.status_changed, rule.triggeredAcciones:
  • Registrar cambios de estado para auditoría
  • Activar flujos de trabajo de cumplimiento
  • Enviar alertas al equipo de cumplimiento
  • Actualizar puntuaciones de riesgo
Escenario: Recibir notificaciones cuando se detectan transacciones de alto riesgo.Eventos: transaction.flagged, alert.createdAcciones:
  • Notificar inmediatamente al equipo de fraude
  • Pausar transacciones relacionadas
  • Solicitar verificación adicional
  • Registrar para investigación
Escenario: Mantener múltiples sistemas sincronizados con datos de Gu1.Eventos: Todos los eventos de entidades y KYCAcciones:
  • Actualizar CRM con estado de verificación
  • Sincronizar con procesador de pagos
  • Actualizar plataforma de analytics
  • Activar automatización de marketing

​
Estructura del Webhook

Todos los webhooks siguen un formato estándar: 
{
  "event": "entity.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "organizationId": "org-123",
  "payload": {
    // Datos específicos del evento
  }
}
Campos comunes:
  • event - Identificador del tipo de evento
  • timestamp - Cuándo ocurrió el evento (ISO 8601)
  • organizationId - Tu ID de organización
  • payload - Datos específicos del evento (varía según el tipo de evento)

​
Mejores Prácticas

Verificar Firmas

Siempre verifica las firmas HMAC para asegurar que las solicitudes provienen de Gu1

Responder Rápidamente

Devuelve estado 200 dentro de 30 segundos, procesa de forma asíncrona

Manejar Idempotencia

Usa IDs de eventos para prevenir procesamiento duplicado

Monitorear Fallos

Rastrea fallos de entrega de webhooks e investiga problemas

​
Rendimiento y Límites

  • Timeout: 30 segundos por intento de entrega
  • Reintentos Máximos: 3 (configurable)
  • Retraso de Reintento: 1s, 2s, 4s (retroceso exponencial)
  • Tamaño de Payload: Hasta 1MB por webhook
  • Límite de Tasa: Sin límite aplicado (entrega de mejor esfuerzo)

​
Obtener Ayuda

Guía de Configuración

Instrucciones paso a paso de configuración

Guía de Seguridad

Implementa verificación de firmas

Referencia de Eventos

Todos los tipos de eventos disponibles

Resolución de Problemas

Problemas comunes y soluciones

​
Próximos Pasos

1

Leer la Guía de Configuración

Aprende cómo configurar webhooks en tu dashboardGuía de Configuración →
2

Explorar Tipos de Eventos

Ve todos los eventos disponibles y sus payloadsEventos de Entidades →Eventos de KYC →
3

Implementar Seguridad

Agrega verificación de firmas a tu endpointGuía de Seguridad →