Skip to main content

​
Descripción General

Esta guía te guía a través de la configuración de webhooks en tu dashboard de Gu1. Los webhooks se configuran a nivel de organización y se aplican a todos los eventos que coincidan con tus filtros.

​
Requisitos Previos

Antes de configurar webhooks, necesitas:
  • ✅ Una cuenta activa de Gu1 con permisos de administrador
  • ✅ Un endpoint HTTPS públicamente accesible para recibir webhooks
  • ✅ (Opcional) Un secreto de webhook para verificación de firmas
Para desarrollo local, usa herramientas como ngrok para crear una URL pública que haga túnel a tu servidor local.

​
Configuración Paso a Paso

​
Paso 1: Navegar a Configuración de Webhooks

  1. Inicia sesión en tu dashboard de Gu1 en app.gu1.ai
  2. Ve a Settings → Webhooks
  3. Haz clic en Add Webhook o Create Webhook

​
Paso 2: Información Básica

1

Nombra tu webhook

Ingresa un nombre descriptivo para identificar este webhookEjemplos:
  • “Production KYC Webhook”
  • “Sandbox Entity Events”
  • “Compliance Monitoring”
2

Agregar descripción (opcional)

Agrega notas sobre para qué se usa este webhookEjemplo: “Envía eventos de aprobación de KYC a nuestro sistema CRM”
3

Ingresar URL del webhook

Proporciona la URL del endpoint HTTPS que recibirá solicitudes POSTRequisitos:
  • Debe usar HTTPS (no HTTP)
  • Debe ser públicamente accesible
  • Debe devolver estado 200 dentro de 30 segundos
Ejemplo: https://api.tuapp.com/webhooks/gu1

​
Paso 3: Seleccionar Ambiente

Elige a qué ambiente se aplica este webhook:
Usar para:
  • Desarrollo y pruebas
  • Ambientes de staging
  • Procesos de QA
Recibe:
  • Eventos de llamadas API de sandbox
  • Validaciones y transacciones de prueba
Puedes crear webhooks separados para sandbox y producción con URLs diferentes. Esto permite pruebas seguras sin afectar sistemas de producción.

​
Paso 4: Suscribirse a Eventos

Selecciona qué tipos de eventos activan este webhook:

​
Opción A: Suscribirse a Todos los Eventos en una Categoría

  • entity.* - Todos los eventos de entidades
  • kyc.* - Todos los eventos de validación de KYC
  • rule.* - Todos los eventos de reglas
  • transaction.* - Todos los eventos de transacciones (próximamente)
  • alert.* - Todos los eventos de alertas (próximamente)

​
Opción B: Suscribirse a Eventos Específicos

Selecciona eventos individuales: Eventos de Entidades:
  • ☐ entity.created
  • ☐ entity.updated
  • ☐ entity.status_changed
  • ☐ entity.deleted (próximamente)
Eventos de KYC:
  • ☐ kyc.validation_created
  • ☐ kyc.validation_in_progress
  • ☐ kyc.validation_approved
  • ☐ kyc.validation_rejected
  • ☐ kyc.validation_abandoned
  • ☐ kyc.validation_expired
Eventos de Reglas:
  • ☐ rule.triggered
Comienza con eventos específicos que necesitas, luego expande a medida que construyes más integraciones. Siempre puedes actualizar las suscripciones más tarde.

​
Paso 5: Configurar Filtros (Opcional)

Agrega filtros para recibir solo eventos relevantes:
Solo activa webhook para tipos de entidades específicas:Opciones:
  • Person
  • Company
  • Device
  • Payment Method
Ejemplo: Solo recibir eventos para entidades de tipo persona, ignorar empresas
Solo activar cuando los cambios de estado coincidan con criterios específicos:Estado Desde: Solo activar cuando cambia DESDE este estado
  • under_review
  • active
  • blocked
  • pending
Estado Hacia: Solo activar cuando cambia HACIA este estado
  • active
  • blocked
  • archived
Ejemplo: Solo activar cuando las entidades cambian HACIA estado blocked
Filtrar eventos basados en la bandera isClient de la entidad:Opciones:
  • Solo clientes (isClient: true)
  • Solo no clientes (isClient: false)
  • Todas las entidades (sin filtro)
Ejemplo: Solo recibir eventos para entidades marcadas como clientes
Agrega filtros avanzados basados en JSON para escenarios complejos:
{
  "entityTypes": ["person"],
  "statusChanges": {
    "to": "blocked"
  },
  "entityTypeFilters": {
    "person": {
      "isClient": true
    }
  }
}
Este ejemplo solo activa para entidades de tipo persona que son clientes cuando cambian a estado bloqueado.

​
Paso 6: Configurar Política de Reintentos (Opcional)

Personaliza cómo Gu1 maneja entregas de webhooks fallidas: 
{
  "maxRetries": 3,
  "retryDelayMs": 1000,
  "backoffMultiplier": 2
}
Parámetros:
  • maxRetries - Intentos de reintento máximos (predeterminado: 3)
  • retryDelayMs - Retraso inicial antes del primer reintento (predeterminado: 1000ms)
  • backoffMultiplier - Multiplicador para retroceso exponencial (predeterminado: 2)
Línea de tiempo de ejemplo con valores predeterminados:
  1. Intento inicial en T+0s
  2. Primer reintento en T+1s (1000ms)
  3. Segundo reintento en T+3s (1000ms × 2)
  4. Tercer reintento en T+7s (1000ms × 2 × 2)
La política de reintentos predeterminada funciona bien para la mayoría de los casos de uso. Solo personaliza si tienes requisitos específicos.

​
Paso 7: Agregar Encabezados Personalizados (Opcional)

Agrega encabezados HTTP personalizados a las solicitudes de webhook: Casos de uso comunes:
  • Tokens de autorización: Authorization: Bearer token123
  • API keys: X-API-Key: your-api-key
  • Identificadores personalizados: X-Webhook-Source: gu1
Formato: 
{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}
Evita enviar secretos sensibles en encabezados personalizados. Usa verificación de firmas en su lugar para autenticación.

​
Paso 8: Guardar Secreto del Webhook

Después de crear el webhook, Gu1 genera automáticamente un secreto:
1

Copiar el secreto

IMPORTANTE: Copia y guarda este secreto inmediatamente. No podrás verlo de nuevo.El secreto se ve como: whsec_abc123def456...
2

Almacenar de forma segura

Guarda el secreto en tus variables de entorno o administrador de secretos:
# archivo .env
GU1_WEBHOOK_SECRET=whsec_abc123def456...
3

Usar para verificación

Usa este secreto para verificar firmas de webhook en tu endpoint.Aprende sobre verificación de firmas →
Nunca comprometas secretos de webhook al control de versiones. Siempre usa variables de entorno o un administrador de secretos.

​
Paso 9: Habilitar Webhook

Cambia el webhook a estado Enabled:
  • ✅ Enabled - Webhook recibe eventos activamente
  • ⏸️ Disabled - Webhook pausado, no se envían eventos
Puedes deshabilitar/habilitar webhooks en cualquier momento sin perder la configuración.

​
Paso 10: Probar tu Webhook

Antes de poner en marcha, prueba tu webhook:
1

Enviar evento de prueba

Haz clic en Test Webhook en el dashboardGu1 envía un payload de prueba:
{
  "event": "webhook.test",
  "timestamp": "2025-01-15T10:30:00Z",
  "webhookId": "webhook-uuid",
  "data": {
    "message": "This is a test webhook from Gu1"
  }
}
2

Verificar recepción

Verifica los logs de tu endpoint para confirmar:
  • ✅ Solicitud recibida
  • ✅ Firma verificada (si está implementada)
  • ✅ Estado 200 devuelto
3

Revisar logs

En el dashboard de Gu1, ve la entrega de prueba:
  • Código de estado HTTP
  • Tiempo de respuesta
  • Cuerpo de respuesta
  • Cualquier error

​
Gestionar Webhooks

​
Ver Lista de Webhooks

Ve a Settings → Webhooks para ver todos los webhooks configurados: Información mostrada:
  • Nombre y descripción
  • URL del endpoint
  • Ambiente (sandbox/production)
  • Estado (enabled/disabled)
  • Suscripciones de eventos
  • Estadísticas (conteos de éxito/fallo)
  • Última marca de tiempo activada

​
Editar Webhook

Haz clic en un webhook para editar:
  • ✏️ Actualizar nombre, descripción o URL
  • 🔔 Cambiar suscripciones de eventos
  • 🎯 Modificar filtros
  • ⚙️ Ajustar política de reintentos
  • 🔄 Agregar/eliminar encabezados personalizados
Los cambios surten efecto inmediatamente.

​
Ver Logs de Webhook

Haz clic en View Logs o History para ver intentos de entrega: Detalles del log:
  • Marca de tiempo de entrega
  • Tipo de evento
  • Código de estado HTTP
  • Tiempo de respuesta
  • Cuerpo de respuesta
  • Número de intento de reintento
  • Mensajes de error (si falló)
Casos de uso:
  • Depurar fallos de entrega
  • Monitorear rendimiento
  • Investigar eventos duplicados
  • Verificar datos de eventos

​
Regenerar Secreto

Si tu secreto de webhook está comprometido:
  1. Haz clic en Regenerate Secret
  2. Copia el nuevo secreto inmediatamente
  3. Actualiza tu aplicación con el nuevo secreto
  4. El secreto antiguo deja de funcionar inmediatamente
Regenerar el secreto invalida el antiguo. Actualiza tu aplicación antes de regenerar para evitar tiempo de inactividad.

​
Deshabilitar/Habilitar Webhook

Pausa temporalmente un webhook sin eliminarlo:
  • Haz clic en el toggle para Disable
  • No se enviarán eventos mientras esté deshabilitado
  • Toda la configuración se preserva
  • Vuelve a habilitar en cualquier momento para reanudar
Casos de uso:
  • Mantenimiento en tu endpoint
  • Depuración de problemas
  • Detener temporalmente el flujo de eventos

​
Eliminar Webhook

Eliminar permanentemente un webhook:
  1. Haz clic en Delete en el webhook
  2. Confirmar eliminación
  3. El webhook se elimina permanentemente
  4. Los logs se conservan por 90 días
La eliminación no se puede deshacer. Considera deshabilitar en su lugar si podrías necesitarlo nuevamente.

​
Monitoreo y Estadísticas

Cada webhook muestra métricas clave:

​
Tasa de Éxito

  • Total Triggers: Intentos de entrega totales
  • Success Count: Entregas exitosas (respuestas 2xx)
  • Failure Count: Entregas fallidas
  • Success Rate: Porcentaje de entregas exitosas

​
Marcas de Tiempo

  • Last Triggered: Intento de entrega más reciente
  • Last Success: Entrega exitosa más reciente
  • Last Failure: Entrega fallida más reciente

​
Rendimiento

  • Average Response Time: Tiempo promedio para que tu endpoint responda
  • P95 Response Time: Tiempo de respuesta percentil 95
Usa estas métricas para:
  • Identificar webhooks problemáticos
  • Monitorear salud del endpoint
  • Optimizar procesamiento de webhooks
  • Detectar problemas de entrega

​
Mejores Prácticas

Nombra los webhooks claramente para identificar su propósito:✅ Bueno: “Production KYC → CRM Integration”❌ Malo: “Webhook 1”
Crea webhooks diferentes para sandbox y producción:
  • URLs diferentes (staging vs production)
  • Prueba primero en sandbox
  • Nunca mezcles ambientes
Empieza con eventos que necesitas, expande después:✅ Inicio: Suscribirse a kyc.validation_approved✅ Después: Agregar kyc.validation_rejected, entity.status_changed
Agrega filtros para reducir ruido:
  • Filtrar por tipo de entidad si solo te interesan personas
  • Filtrar por cambios de estado para transiciones específicas
  • Usar filtros personalizados para escenarios complejos
Revisa la salud del webhook semanalmente:
  • Revisar tasas de éxito
  • Investigar fallos
  • Verificar tiempos de respuesta
  • Actualizar filtros según sea necesario
Mantén documentación interna:
  • Qué webhook maneja qué
  • Qué acciones activa
  • Quién es dueño de la integración
  • Pasos de resolución de problemas

​
Resolución de Problemas

Lista de verificación:
  • ✅ Webhook está habilitado
  • ✅ Ambiente correcto seleccionado
  • ✅ Suscrito a tipos de eventos correctos
  • ✅ Filtros no demasiado restrictivos
  • ✅ URL es correcta y accesible
  • ✅ Endpoint devuelve estado 200
Verifica los logs de webhook para intentos de entrega y errores.
Causas comunes:
  • Endpoint está caído o inalcanzable
  • Firewall bloqueando solicitudes de Gu1
  • Endpoint expirando (>30s)
  • Endpoint devolviendo estado no-2xx
  • Problemas de certificado SSL
Verifica los logs de tu servidor y los logs de entrega de webhook en Gu1.
Soluciones:
  • Agregar filtros para reducir alcance
  • Desuscribirse de tipos de eventos no usados
  • Usar filtros de tipo de entidad
  • Agregar filtros de cambio de estado
Revisa qué eventos realmente necesitas.
Esto es comportamiento normal debido a reintentos. Siempre implementa idempotencia usando IDs de eventos.Aprende sobre manejo de duplicados →

​
Próximos Pasos

Implementar tu Endpoint

Crea un endpoint con verificación de firmas

Explorar Tipos de Eventos

Ve todos los eventos disponibles y payloads

Revisar Guía de Seguridad

Aprende sobre verificación de firmas HMAC

Ver Código de Ejemplo

Ve ejemplos de implementación completos