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

# Overview

> Receive messages, statuses, calls, group changes and instance state in real time via webhook or WebSocket

The **Events** module is how you receive what happens in your instance **in real time**. RyzeAPI emits events through **two independent channels** that share the same envelope and the same catalog:

<CardGroup cols={2}>
  <Card title="Webhook (HTTP push)" icon="webhook">
    RyzeAPI `POST`s to your URL every time an event occurs. Persisted in a queue with retry/backoff and DLQ. Ideal for servers, CRMs, automations.
  </Card>

  <Card title="WebSocket (real-time push)" icon="plug">
    The client opens a connection and receives events instantly. No persistence, ideal for dashboards, live panels, support screens.
  </Card>
</CardGroup>

<Tip>
  Nothing stops you from using both at once: the webhook handles persistent delivery to the backend while the WebSocket makes the UI react the moment the event arrives.
</Tip>

## Module endpoints

| Method | Path                                 | Function                                            |
| ------ | ------------------------------------ | --------------------------------------------------- |
| `POST` | `/api/events/webhook/:instance`      | Configure webhook (up to 3 enabled)                 |
| `GET`  | `/api/events/getWebhook/:instance`   | List webhooks or get one by `?label=`               |
| `POST` | `/api/events/websocket/:instance`    | Configure WebSocket (`{"enabled": false}` disables) |
| `GET`  | `/api/events/getWebsocket/:instance` | Read current WebSocket config                       |
| `GET`  | `/ws/:instance`                      | Connect via WebSocket (upgrade)                     |

<Note>
  Webhook and WebSocket configuration can also be done **at instance creation**, just send `webhookEnabled`, `webhookURL`, `websocketEnabled`, etc. in the body of [`POST /api/instance/new`](/en/api/instance/create).
</Note>

## Shared envelope

Both webhook and WebSocket deliver the same object:

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

`instanceData.token` is the instance's own token, useful when your consumer centralizes multiple instances and needs to identify the source.

## The 6 event types

<CardGroup cols={2}>
  <Card title="message.exchange" icon="message">
    Messages sent/received (text, media, sticker, doc, poll, contact, location, button/list, edits and revocations).
  </Card>

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

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

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

  <Card title="instance.state" icon="signal">
    Instance connection changes: `connected`, `qr_ready`, `temp_banned`, `logged_out`, `pair_success`...
  </Card>

  <Card title="label.update" icon="tag">
    WhatsApp Business labels: edits, association with chats and messages.
  </Card>
</CardGroup>

<Card title="Full event catalog" icon="book" href="/en/api/events/catalog">
  Payload schemas, enums and examples for each of the 6 types.
</Card>

## Webhook vs WebSocket

| Aspect                   | Webhook                                           | WebSocket                                                |
| ------------------------ | ------------------------------------------------- | -------------------------------------------------------- |
| Protocol                 | HTTP POST                                         | WS (TCP upgrade)                                         |
| Delivery                 | Async, persisted in queue                         | Real-time, in memory                                     |
| Retry/DLQ                | Exponential backoff 1s→1h, up to 5 attempts + DLQ | No retry, events lost if client offline                  |
| Event filter             | `events[]` per config                             | `events[]` per config                                    |
| Base64 media             | `mediaBase64` optional                            | `mediaBase64` optional                                   |
| Authentication           | Configurable `Authorization` header               | Token on upgrade (header or `?token=`)                   |
| Heartbeat                | N/A                                               | PING/PONG \~54s/60s                                      |
| Limit                    | Up to **3 enabled webhooks** per instance         | 1 config per instance (broadcast to N connected clients) |
| Backpressure             | Queue grows in DB                                 | 256-msg buffer per client; slow ones are dropped         |
| Survives consumer crash? | Yes                                               | No                                                       |

## Multiple webhooks per instance

Each instance accepts up to **3 simultaneously enabled webhooks**, identified by a `label`. This lets you, for example:

* `default` for the main production system
* `analytics-pipeline` for an event sink
* `staging-mirror` to validate changes in parallel

Each `label` has its own URL, event filter, `authorization` and `mediaBase64`. See [configure webhook](/en/api/events/webhook-configure).

## Best practices

<Check>**Respond 2xx in under 5s** on the webhook endpoint, otherwise delivery enters retry with exponential backoff.</Check>
<Check>**Validate the origin** with the configured `Authorization` header, there is no automatic HMAC, the consumer is responsible.</Check>
<Check>**`mediaBase64: false`** if you only need the URL/`s3Url`, saves bandwidth and DB space.</Check>
<Check>**Reconnect with backoff** on the WebSocket, there is no session resume; lost events do not come back.</Check>
<Check>**Filter `events[]`** when you know exactly what you'll consume, reducing traffic and processing.</Check>

## Next steps

<CardGroup cols={2}>
  <Card title="Configure webhook" icon="webhook" href="/en/api/events/webhook-configure">
    `POST /api/events/webhook/:instance`, creates/updates by `label`.
  </Card>

  <Card title="List webhooks" icon="list" href="/en/api/events/webhook-list">
    `GET /api/events/getWebhook/:instance`, all or by `?label=`.
  </Card>

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

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

  <Card title="Event catalog" icon="book" href="/en/api/events/catalog">
    Schemas and examples for the 6 types.
  </Card>

  <Card title="Connect via WebSocket" icon="bolt" href="/en/api/websocket">
    `GET /ws/:instance`, protocol, auth, reconnection.
  </Card>
</CardGroup>