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

# Resumen

> Recibe mensajes, estados, llamadas, cambios de grupo y estado de instancia en tiempo real vía webhook o WebSocket

El módulo de **Eventos** es la forma de recibir lo que ocurre en tu instancia **en tiempo real**. RyzeAPI emite eventos a través de **dos canales independientes** que comparten el mismo envoltorio y el mismo catálogo:

<CardGroup cols={2}>
  <Card title="Webhook (HTTP push)" icon="webhook">
    RyzeAPI hace `POST` a tu URL cada vez que ocurre un evento. Persistido en una cola con retry/backoff y DLQ. Ideal para servidores, CRMs, automatizaciones.
  </Card>

  <Card title="WebSocket (push en tiempo real)" icon="plug">
    El cliente abre una conexión y recibe los eventos al instante. Sin persistencia, ideal para dashboards, paneles en vivo, pantallas de soporte.
  </Card>
</CardGroup>

<Tip>
  Nada impide usar ambos a la vez: el webhook se encarga de la entrega persistente al backend mientras el WebSocket hace que la UI reaccione en el momento en que llega el evento.
</Tip>

## Endpoints del módulo

| Método | Ruta                                 | Función                                               |
| ------ | ------------------------------------ | ----------------------------------------------------- |
| `POST` | `/api/events/webhook/:instance`      | Configurar webhook (hasta 3 habilitados)              |
| `GET`  | `/api/events/getWebhook/:instance`   | Listar webhooks u obtener uno por `?label=`           |
| `POST` | `/api/events/websocket/:instance`    | Configurar WebSocket (`{"enabled": false}` desactiva) |
| `GET`  | `/api/events/getWebsocket/:instance` | Leer la configuración actual del WebSocket            |
| `GET`  | `/ws/:instance`                      | Conectar vía WebSocket (upgrade)                      |

<Note>
  La configuración de webhook y WebSocket también puede hacerse **en la creación de la instancia**, basta con enviar `webhookEnabled`, `webhookURL`, `websocketEnabled`, etc. en el body de [`POST /api/instance/new`](/es/api/instance/create).
</Note>

## Envoltorio compartido

Tanto el webhook como el WebSocket entregan el mismo objeto:

```json theme={null}
{
  "event": "message.exchange",
  "data": { /* event-specific payload */ },
  "instanceData": {
    "baseUrl": "https://api.example.com",
    "instance": "$Instance_Name",
    "token": "<instance-token>"
  }
}
```

`instanceData.token` es el propio token de la instancia, útil cuando tu consumidor centraliza varias instancias y necesita identificar el origen.

## Los 6 tipos de eventos

<CardGroup cols={2}>
  <Card title="message.exchange" icon="message">
    Mensajes enviados/recibidos (texto, media, sticker, doc, encuesta, contacto, ubicación, botón/lista, ediciones y revocaciones).
  </Card>

  <Card title="message.status" icon="check-double">
    Acuses de entrega: `delivered`, `read`, `played`, `read_self`, `played_self`, etc.
  </Card>

  <Card title="call.update" icon="phone">
    Llamadas: `offer`, `accepted`, `rejected`, `terminated`, `notification`, `latency`.
  </Card>

  <Card title="group.flow" icon="users">
    Cambios de grupo: `joined`/`left`/`promoted`/`demoted` + metadatos (`name`, `topic`, `announce`, `link`, etc.).
  </Card>

  <Card title="instance.state" icon="signal">
    Cambios de conexión de la instancia: `connected`, `qr_ready`, `temp_banned`, `logged_out`, `pair_success`...
  </Card>

  <Card title="label.update" icon="tag">
    Etiquetas de WhatsApp Business: ediciones, asociación con chats y mensajes.
  </Card>
</CardGroup>

<Card title="Catálogo completo de eventos" icon="book" href="/es/api/events/catalog">
  Esquemas de payload, enums y ejemplos para cada uno de los 6 tipos.
</Card>

## Webhook vs WebSocket

| Aspecto                            | Webhook                                           | WebSocket                                                         |
| ---------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
| Protocolo                          | HTTP POST                                         | WS (TCP upgrade)                                                  |
| Entrega                            | Asíncrona, persistida en cola                     | Tiempo real, en memoria                                           |
| Retry/DLQ                          | Backoff exponencial 1s→1h, hasta 5 intentos + DLQ | Sin retry, los eventos se pierden si el cliente está offline      |
| Filtro de eventos                  | `events[]` por configuración                      | `events[]` por configuración                                      |
| Media en base64                    | `mediaBase64` opcional                            | `mediaBase64` opcional                                            |
| Autenticación                      | Cabecera `Authorization` configurable             | Token en el upgrade (cabecera o `?token=`)                        |
| Heartbeat                          | N/A                                               | PING/PONG \~54s/60s                                               |
| Límite                             | Hasta **3 webhooks habilitados** por instancia    | 1 configuración por instancia (broadcast a N clientes conectados) |
| Backpressure                       | La cola crece en la BD                            | Buffer de 256 mensajes por cliente; los lentos se descartan       |
| ¿Sobrevive a crash del consumidor? | Sí                                                | No                                                                |

## Múltiples webhooks por instancia

Cada instancia acepta hasta **3 webhooks habilitados simultáneamente**, identificados por un `label`. Esto te permite, por ejemplo:

* `default` para el sistema principal de producción
* `analytics-pipeline` para un sink de eventos
* `staging-mirror` para validar cambios en paralelo

Cada `label` tiene su propia URL, filtro de eventos, `authorization` y `mediaBase64`. Ver [configurar webhook](/es/api/events/webhook-configure).

## Buenas prácticas

<Check>**Responde 2xx en menos de 5s** en el endpoint del webhook, de lo contrario la entrega entra en retry con backoff exponencial.</Check>
<Check>**Valida el origen** con la cabecera `Authorization` configurada, no hay HMAC automático, el consumidor es responsable.</Check>
<Check>**`mediaBase64: false`** si solo necesitas la URL/`s3Url`, ahorra ancho de banda y espacio en BD.</Check>
<Check>**Reconecta con backoff** en el WebSocket, no hay reanudación de sesión; los eventos perdidos no regresan.</Check>
<Check>**Filtra `events[]`** cuando sepas exactamente lo que vas a consumir, reduciendo tráfico y procesamiento.</Check>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Configurar webhook" icon="webhook" href="/es/api/events/webhook-configure">
    `POST /api/events/webhook/:instance`, crea/actualiza por `label`.
  </Card>

  <Card title="Listar webhooks" icon="list" href="/es/api/events/webhook-list">
    `GET /api/events/getWebhook/:instance`, todos o por `?label=`.
  </Card>

  <Card title="Configurar WebSocket" icon="plug" href="/es/api/events/websocket-configure">
    `POST /api/events/websocket/:instance`, `enabled`, `events`, `mediaBase64`.
  </Card>

  <Card title="Consultar configuración del WebSocket" icon="eye" href="/es/api/events/websocket-read">
    `GET /api/events/getWebsocket/:instance`.
  </Card>

  <Card title="Catálogo de eventos" icon="book" href="/es/api/events/catalog">
    Esquemas y ejemplos de los 6 tipos.
  </Card>

  <Card title="Conectar vía WebSocket" icon="bolt" href="/es/api/websocket">
    `GET /ws/:instance`, protocolo, autenticación, reconexión.
  </Card>
</CardGroup>