> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Descripción General de Webhooks

> Notificaciones en tiempo real para todos los eventos en tu organización de Gu1 — con eventos webhook de gu1 para integración downstream en tiempo real.

## ¿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?

<CardGroup cols={2}>
  <Card title="Actualizaciones en Tiempo Real" icon="bolt">
    Recibe notificaciones instantáneas cuando ocurren eventos
  </Card>

  <Card title="Eficiente" icon="gauge-high">
    No es necesario consultar la API repetidamente
  </Card>

  <Card title="Flujos de Trabajo Automatizados" icon="robot">
    Activa acciones automáticamente basadas en eventos
  </Card>

  <Card title="Escalable" icon="chart-line">
    Maneja grandes volúmenes sin impacto en el rendimiento
  </Card>
</CardGroup>

## Cómo Funcionan los Webhooks

```mermaid theme={null}
sequenceDiagram
    participant App as Tu Aplicación
    participant Gu1 as Plataforma Gu1
    participant Endpoint as Tu Endpoint de Webhook

    App->>Gu1: Configurar URL del webhook
    Note over Gu1: Ocurre un evento<br/>(entidad creada, KYC aprobado, etc.)
    Gu1->>Endpoint: POST /webhooks<br/>con datos del evento
    Endpoint->>Gu1: 200 OK
    Note over Endpoint: Procesar evento<br/>de forma asíncrona
```

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 →](/es/webhooks/events/entity-events)

### 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 →](/es/webhooks/events/kyc-events)

### 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 →](/es/webhooks/events/rule-events)

### Eventos de Análisis de Riesgo

Reciba notificaciones cuando finalice una ejecución de matriz de riesgo:

* `risk_analysis_entity_executed` - Matriz de riesgo ejecutada en persona o empresa
* `risk_analysis_transaction_executed` - Matriz de riesgo ejecutada en transacción

[Más información sobre Eventos de Análisis de Riesgo →](/es/webhooks/events/risk-analysis-events)

### Eventos de Seguridad e IAM

Monitoree autenticación, miembros, roles y configuración de seguridad para integraciones SIEM:

* `security.auth.login_succeeded` / `security.auth.logout` / `security.auth.login_failed`
* `security.member.*` - Invitación, alta, baja, activación, perfil, contraseña (admin), equipos, canales y acceso a entornos (production/sandbox)
* `security.role.*` - ABM de roles, asignación y revocación
* `security.rbac.granular_toggled` - RBAC granular habilitado/deshabilitado
* `security.settings.updated` - Sandbox y otros parámetros de seguridad auditados

[Más información sobre Eventos de Seguridad →](/es/webhooks/events/security-events)

### Eventos de Transacciones (Próximamente)

Monitorea actividad de transacciones:

* `transaction.created` - Nueva transacción registrada
* `transaction.updated` - Transacción actualizada (instantánea completa; incluye cambios de estado)
* `transaction.status_changed` - Solo cambio de estado (payload compacto cuando cambia el estado)
* `transaction.flagged` - Transacción marcada como sospechosa

[Más información sobre eventos de transacciones →](/es/webhooks/events/transaction-events)

### 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:

<Steps>
  <Step title="Configurar Webhook">
    Ve a **Configuración → Webhooks** y crea un nuevo webhook con la URL de tu endpoint.

    [Guía de Configuración →](/es/webhooks/configuration)
  </Step>

  <Step title="Suscribirse a Eventos">
    Selecciona qué tipos de eventos deseas recibir (ej., `entity.*`, `kyc.*`).
  </Step>

  <Step title="Implementar Endpoint">
    Crea un endpoint HTTPS que reciba solicitudes POST y verifique firmas.

    [Guía de Seguridad →](/es/webhooks/security)
  </Step>
</Steps>

## Casos de Uso Comunes

<AccordionGroup>
  <Accordion title="Onboarding Automatizado de Clientes">
    **Escenario**: Activar automáticamente cuentas de clientes cuando se aprueba el KYC.

    **Eventos**: `kyc.validation_approved`

    **Acciones**:

    * Actualizar estado del cliente en tu base de datos
    * Enviar correo de bienvenida
    * Habilitar funciones de cuenta
    * Notificar a equipos internos
  </Accordion>

  <Accordion title="Monitoreo de Cumplimiento en Tiempo Real">
    **Escenario**: Rastrear cambios de estado de entidades para informes de cumplimiento.

    **Eventos**: `entity.status_changed`, `rule.triggered`

    **Acciones**:

    * Registrar cambios de estado para auditoría
    * Activar flujos de trabajo de cumplimiento
    * Enviar alertas al equipo de cumplimiento
    * Actualizar puntuaciones de riesgo
  </Accordion>

  <Accordion title="Alertas de Riesgo de Transacciones">
    **Escenario**: Recibir notificaciones cuando se detectan transacciones de alto riesgo.

    **Eventos**: `transaction.flagged`, `alert.created`

    **Acciones**:

    * Notificar inmediatamente al equipo de fraude
    * Pausar transacciones relacionadas
    * Solicitar verificación adicional
    * Registrar para investigación
  </Accordion>

  <Accordion title="Integración Multi-Sistema">
    **Escenario**: Mantener múltiples sistemas sincronizados con datos de Gu1.

    **Eventos**: Todos los eventos de entidades y KYC

    **Acciones**:

    * Actualizar CRM con estado de verificación
    * Sincronizar con procesador de pagos
    * Actualizar plataforma de analytics
    * Activar automatización de marketing
  </Accordion>
</AccordionGroup>

## Estructura del Webhook

Todos los webhooks siguen un formato estándar:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Verificar Firmas" icon="shield-check">
    Siempre verifica las firmas HMAC para asegurar que las solicitudes provienen de Gu1
  </Card>

  <Card title="Responder Rápidamente" icon="gauge-max">
    Devuelve estado 200 dentro de 30 segundos, procesa de forma asíncrona
  </Card>

  <Card title="Manejar Idempotencia" icon="repeat">
    Usa IDs de eventos para prevenir procesamiento duplicado
  </Card>

  <Card title="Monitorear Fallos" icon="chart-line">
    Rastrea fallos de entrega de webhooks e investiga problemas
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Guía de Configuración" icon="gear" href="/es/webhooks/configuration">
    Instrucciones paso a paso de configuración
  </Card>

  <Card title="Guía de Seguridad" icon="lock" href="/es/webhooks/security">
    Implementa verificación de firmas
  </Card>

  <Card title="Referencia de Eventos" icon="list" href="/es/webhooks/events/entity-events">
    Todos los tipos de eventos disponibles
  </Card>

  <Card title="Resolución de Problemas" icon="wrench" href="/es/webhooks/security">
    Problemas comunes y soluciones
  </Card>
</CardGroup>

## Próximos Pasos

<Steps>
  <Step title="Leer la Guía de Configuración">
    Aprende cómo configurar webhooks en tu dashboard

    [Guía de Configuración →](/es/webhooks/configuration)
  </Step>

  <Step title="Explorar Tipos de Eventos">
    Ve todos los eventos disponibles y sus payloads

    [Eventos de Entidades →](/es/webhooks/events/entity-events)

    [Eventos de KYC →](/es/webhooks/events/kyc-events)
  </Step>

  <Step title="Implementar Seguridad">
    Agrega verificación de firmas a tu endpoint

    [Guía de Seguridad →](/es/webhooks/security)
  </Step>
</Steps>