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

# Visão Geral

> Receba mensagens, status, chamadas, mudanças de grupo e estado da instância em tempo real via webhook ou WebSocket

O módulo **Eventos** é como você recebe o que acontece na sua instância **em tempo real**. A RyzeAPI emite eventos por **dois canais independentes** que compartilham o mesmo envelope e o mesmo catálogo:

<CardGroup cols={2}>
  <Card title="Webhook (HTTP push)" icon="webhook">
    A RyzeAPI faz `POST` na sua URL toda vez que um evento ocorre. Persistido em fila com retry/backoff e DLQ. Ideal para servidores, CRMs, automações.
  </Card>

  <Card title="WebSocket (push em tempo real)" icon="plug">
    O cliente abre uma conexão e recebe os eventos na hora. Sem persistência, ideal para dashboards, painéis ao vivo, telas de atendimento.
  </Card>
</CardGroup>

<Tip>
  Nada impede usar os dois ao mesmo tempo: webhook cuida da entrega persistente para o backend, WebSocket faz a UI saltar quando o evento chega.
</Tip>

## Endpoints do módulo

| Método | Path                                 | Função                                                 |
| ------ | ------------------------------------ | ------------------------------------------------------ |
| `POST` | `/api/events/webhook/:instance`      | Configurar webhook (até 3 habilitados)                 |
| `GET`  | `/api/events/getWebhook/:instance`   | Listar webhooks ou obter um por `?label=`              |
| `POST` | `/api/events/websocket/:instance`    | Configurar WebSocket (`{"enabled": false}` desabilita) |
| `GET`  | `/api/events/getWebsocket/:instance` | Ler config atual do WebSocket                          |
| `GET`  | `/ws/:instance`                      | Conectar via WebSocket (upgrade)                       |

<Note>
  A configuração de webhook e WebSocket também pode ser feita **na criação da instância**, basta enviar `webhookEnabled`, `webhookURL`, `websocketEnabled`, etc. no body de [`POST /api/instance/new`](/pt/api/instance/create).
</Note>

## Envelope compartilhado

Tanto webhook quanto WebSocket entregam o mesmo objeto:

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

`instanceData.token` é o token da própria instância, útil quando seu consumidor centraliza várias instâncias e precisa identificar a origem.

## Os 6 tipos de evento

<CardGroup cols={2}>
  <Card title="message.exchange" icon="message">
    Mensagens enviadas/recebidas (texto, mídia, sticker, doc, enquete, contato, localização, botão/lista, edits e revogações).
  </Card>

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

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

  <Card title="group.flow" icon="users">
    Mudanças em grupos: `joined`/`left`/`promoted`/`demoted` + metadata (`name`, `topic`, `announce`, `link`, etc.).
  </Card>

  <Card title="instance.state" icon="signal">
    Mudanças de conexão da instância: `connected`, `qr_ready`, `temp_banned`, `logged_out`, `pair_success`...
  </Card>

  <Card title="label.update" icon="tag">
    Etiquetas WhatsApp Business: edição, associação a chats e mensagens.
  </Card>
</CardGroup>

<Card title="Catálogo completo de eventos" icon="book" href="/pt/api/events/catalog">
  Schemas de payload, enums e exemplos de cada um dos 6 tipos.
</Card>

## Webhook x WebSocket

| Aspecto                        | Webhook                                           | WebSocket                                                  |
| ------------------------------ | ------------------------------------------------- | ---------------------------------------------------------- |
| Protocolo                      | HTTP POST                                         | WS (upgrade TCP)                                           |
| Entrega                        | Async, persistida em fila                         | Real-time, em memória                                      |
| Retry/DLQ                      | Backoff exponencial 1s→1h, até 5 tentativas + DLQ | Sem retry, eventos perdidos se cliente offline             |
| Filtro de eventos              | `events[]` por config                             | `events[]` por config                                      |
| Mídia em base64                | `mediaBase64` opcional                            | `mediaBase64` opcional                                     |
| Autenticação                   | Header `Authorization` configurável               | Token no upgrade (header ou `?token=`)                     |
| Heartbeat                      | N/A                                               | PING/PONG \~54s/60s                                        |
| Limite                         | Até **3 webhooks habilitados** por instância      | 1 config por instância (broadcast a N clientes conectados) |
| Backpressure                   | Fila cresce no DB                                 | Buffer de 256 msgs por cliente; lentos são dropados        |
| Sobrevive a queda do consumer? | Sim                                               | Não                                                        |

## Múltiplos webhooks por instância

Cada instância aceita até **3 webhooks habilitados simultâneos**, você os identifica por um `label`. Permite, por exemplo:

* `default` para o sistema principal de produção
* `analytics-pipeline` para um sink de eventos
* `staging-mirror` para validar mudanças em paralelo

Cada `label` tem URL, eventos filtrados, `authorization` e `mediaBase64` próprios. Ver [configurar webhook](/pt/api/events/webhook-configure).

## Boas práticas

<Check>**Responda 2xx em menos de 5s** no endpoint webhook, caso contrário, a entrega entra em retry com backoff exponencial.</Check>
<Check>**Valide a origem** com o header `Authorization` configurado, não há HMAC automático, o consumidor é responsável.</Check>
<Check>**`mediaBase64: false`** se você precisa só da URL/`s3Url`, economiza banda e DB.</Check>
<Check>**Reconecte com backoff** no WebSocket, não há resumo de sessão; eventos perdidos não voltam.</Check>
<Check>**Filtre `events[]`** quando souber exatamente o que vai consumir, reduz tráfego e processamento.</Check>

## Próximos passos

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

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

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

  <Card title="Verificar config do WebSocket" icon="eye" href="/pt/api/events/websocket-read">
    `GET /api/events/getWebsocket/:instance`.
  </Card>

  <Card title="Catálogo de eventos" icon="book" href="/pt/api/events/catalog">
    Schemas e exemplos dos 6 tipos.
  </Card>

  <Card title="Conectar via WebSocket" icon="bolt" href="/pt/api/websocket">
    `GET /ws/:instance`, protocolo, auth, reconexão.
  </Card>
</CardGroup>