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

# Configuración de Webhooks

> Guía paso a paso para configurar webhooks en tu dashboard de Gu1 — con eventos webhook de gu1 para integración downstream en tiempo real.

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

No necesitas proporcionar un secreto de webhook. Gu1 **genera automáticamente** un secreto al crear un webhook. El dashboard **muestra el secreto una sola vez** justo después de crear (o regenerar) el webhook—cópialo ahí; no se vuelve a mostrar en la lista de webhooks. **Tus webhooks recibirán eventos aunque no verifiques la firma**; verificar la firma (con el secreto y la cabecera `X-Webhook-Signature`) es opcional pero recomendable para que tu endpoint pueda confirmar que la petición viene de Gu1. El payload del **monitor de webhooks** es solo para debugging: la verificación debe hacerse sobre el **raw body HTTP** al recibir el request; ver [Seguridad de webhooks](/es/webhooks/security#fallos-intermitentes-de-firma).

<Note>
  Para desarrollo local, usa herramientas como [ngrok](https://ngrok.com/) para crear una URL pública que haga túnel a tu servidor local.
</Note>

## 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](https://app.gu1.ai)
2. Ve a **Settings** → **Webhooks**
3. Haz clic en **Add Webhook** o **Create Webhook**

### Paso 2: Información Básica

<Steps>
  <Step title="Nombra tu webhook">
    Ingresa un nombre descriptivo para identificar este webhook

    **Ejemplos**:

    * "Production KYC Webhook"
    * "Sandbox Entity Events"
    * "Compliance Monitoring"
  </Step>

  <Step title="Agregar descripción (opcional)">
    Agrega notas sobre para qué se usa este webhook

    **Ejemplo**: "Envía eventos de aprobación de KYC a nuestro sistema CRM"
  </Step>

  <Step title="Ingresar URL del webhook">
    Proporciona la URL del endpoint HTTPS que recibirá solicitudes POST

    **Requisitos**:

    * 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`
  </Step>
</Steps>

### Paso 3: Seleccionar Ambiente

Elige a qué ambiente se aplica este webhook:

<Tabs>
  <Tab title="Sandbox">
    **Usar para**:

    * Desarrollo y pruebas
    * Ambientes de staging
    * Procesos de QA

    **Recibe**:

    * Eventos de llamadas API de sandbox
    * Validaciones y transacciones de prueba
  </Tab>

  <Tab title="Production">
    **Usar para**:

    * Sistemas de producción en vivo
    * Datos reales de clientes
    * Flujos de trabajo críticos

    **Recibe**:

    * Eventos de llamadas API de producción
    * Verificaciones reales de clientes
  </Tab>
</Tabs>

<Note>
  Puedes crear webhooks separados para sandbox y producción con URLs diferentes. Esto permite pruebas seguras sin afectar sistemas de producción.
</Note>

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

<Tip>
  Comienza con eventos específicos que necesitas, luego expande a medida que construyes más integraciones. Siempre puedes actualizar las suscripciones más tarde.
</Tip>

### Paso 5: Configurar Filtros (Opcional)

Agrega filtros para recibir solo eventos relevantes:

<Accordion title="Filtrar por Tipo de Entidad">
  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
</Accordion>

<Accordion title="Filtrar por Cambios de Estado">
  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`
</Accordion>

<Accordion title="Filtrar por Bandera de Cliente">
  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
</Accordion>

<Accordion title="Filtros Personalizados">
  Agrega filtros avanzados basados en JSON para escenarios complejos:

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

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

Personaliza cómo Gu1 maneja entregas de webhooks fallidas:

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

<Tip>
  La política de reintentos predeterminada funciona bien para la mayoría de los casos de uso. Solo personaliza si tienes requisitos específicos.
</Tip>

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

```json theme={null}
{
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-key",
  "X-Custom-Header": "custom-value"
}
```

<Warning>
  Evita enviar secretos sensibles en encabezados personalizados. Usa verificación de firmas en su lugar para autenticación.
</Warning>

### Paso 8: Copiar el Secreto Generado

No necesitas proporcionar un secreto al crear el webhook. Después de guardarlo, Gu1 genera automáticamente un secreto y **el dashboard lo muestra una sola vez** en el paso de éxito al crear. Cópialo ahí—no se volverá a mostrar en la lista de webhooks (puedes regenerar uno nuevo después en la configuración del webhook si lo necesitas).

<Steps>
  <Step title="Copiar el secreto">
    **IMPORTANTE**: Copia y guarda este secreto inmediatamente. No podrás verlo de nuevo en la lista.

    El secreto se ve como: `whsec_abc123def456...`
  </Step>

  <Step title="Almacenar de forma segura">
    Guarda el secreto en tus variables de entorno o administrador de secretos:

    ```bash theme={null}
    # archivo .env
    GU1_WEBHOOK_SECRET=whsec_abc123def456...
    ```
  </Step>

  <Step title="Usar para verificación (opcional)">
    Usa este secreto para verificar firmas de webhook en tu endpoint (cabecera `X-Webhook-Signature`). **La verificación es opcional**: tu webhook recibirá eventos aunque no verifiques; verificar es recomendable por seguridad.

    [Aprende sobre verificación de firmas →](/es/webhooks/security)
  </Step>
</Steps>

<Warning>
  Nunca comprometas secretos de webhook al control de versiones. Siempre usa variables de entorno o un administrador de secretos.
</Warning>

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

<Steps>
  <Step title="Enviar evento de prueba">
    Haz clic en **Test Webhook** en el dashboard

    Gu1 envía un payload de prueba:

    ```json theme={null}
    {
      "event": "webhook.test",
      "timestamp": "2025-01-15T10:30:00Z",
      "webhookId": "webhook-uuid",
      "data": {
        "message": "This is a test webhook from Gu1"
      }
    }
    ```
  </Step>

  <Step title="Verificar recepción">
    Verifica los logs de tu endpoint para confirmar:

    * ✅ Solicitud recibida
    * ✅ Firma verificada (si está implementada)
    * ✅ Estado 200 devuelto
  </Step>

  <Step title="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
  </Step>
</Steps>

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

<Warning>
  Regenerar el secreto invalida el antiguo. Actualiza tu aplicación antes de regenerar para evitar tiempo de inactividad.
</Warning>

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

<Warning>
  La eliminación no se puede deshacer. Considera deshabilitar en su lugar si podrías necesitarlo nuevamente.
</Warning>

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

<AccordionGroup>
  <Accordion title="Usar Nombres Descriptivos">
    Nombra los webhooks claramente para identificar su propósito:

    ✅ Bueno: "Production KYC → CRM Integration"

    ❌ Malo: "Webhook 1"
  </Accordion>

  <Accordion title="Separar Ambientes">
    Crea webhooks diferentes para sandbox y producción:

    * URLs diferentes (staging vs production)
    * Prueba primero en sandbox
    * Nunca mezcles ambientes
  </Accordion>

  <Accordion title="Comenzar con Eventos Específicos">
    Empieza con eventos que necesitas, expande después:

    ✅ Inicio: Suscribirse a `kyc.validation_approved`

    ✅ Después: Agregar `kyc.validation_rejected`, `entity.status_changed`
  </Accordion>

  <Accordion title="Usar Filtros Sabiamente">
    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
  </Accordion>

  <Accordion title="Monitorear Regularmente">
    Revisa la salud del webhook semanalmente:

    * Revisar tasas de éxito
    * Investigar fallos
    * Verificar tiempos de respuesta
    * Actualizar filtros según sea necesario
  </Accordion>

  <Accordion title="Documentar tus Webhooks">
    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
  </Accordion>
</AccordionGroup>

## Resolución de Problemas

<AccordionGroup>
  <Accordion title="Webhook No Recibe Eventos">
    **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.
  </Accordion>

  <Accordion title="Todas las Entregas Fallan">
    **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.
  </Accordion>

  <Accordion title="Recibiendo Demasiados Eventos">
    **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.
  </Accordion>

  <Accordion title="Eventos Duplicados">
    Esto es comportamiento normal debido a reintentos. Siempre implementa idempotencia usando IDs de eventos.

    [Aprende sobre manejo de duplicados →](/es/webhooks/security)
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Implementar tu Endpoint" icon="code" href="/es/webhooks/security">
    Crea un endpoint con verificación de firmas
  </Card>

  <Card title="Explorar Tipos de Eventos" icon="list" href="/es/webhooks/events/entity-events">
    Ve todos los eventos disponibles y payloads
  </Card>

  <Card title="Revisar Guía de Seguridad" icon="shield-check" href="/es/webhooks/security">
    Aprende sobre verificación de firmas HMAC
  </Card>

  <Card title="Ver Código de Ejemplo" icon="file-code" href="/es/webhooks/events/kyc-events">
    Ve ejemplos de implementación completos
  </Card>
</CardGroup>