Skip to main content

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.

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:

Webhook (HTTP push)

RyzeAPI POSTs to your URL every time an event occurs. Persisted in a queue with retry/backoff and DLQ. Ideal for servers, CRMs, automations.

WebSocket (real-time push)

The client opens a connection and receives events instantly. No persistence, ideal for dashboards, live panels, support screens.
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.

​
Module endpoints

MethodPathFunction
POST/api/events/webhook/:instanceConfigure webhook (up to 3 enabled)
GET/api/events/getWebhook/:instanceList webhooks or get one by ?label=
POST/api/events/websocket/:instanceConfigure WebSocket ({"enabled": false} disables)
GET/api/events/getWebsocket/:instanceRead current WebSocket config
GET/ws/:instanceConnect via WebSocket (upgrade)
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.

​
Shared envelope

Both webhook and WebSocket deliver the same object: 
{
  "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

message.exchange

Messages sent/received (text, media, sticker, doc, poll, contact, location, button/list, edits and revocations).

message.status

Delivery receipts: delivered, read, played, read_self, played_self, etc.

call.update

Calls: offer, accepted, rejected, terminated, notification, latency.

group.flow

Group changes: joined/left/promoted/demoted + metadata (name, topic, announce, link, etc.).

instance.state

Instance connection changes: connected, qr_ready, temp_banned, logged_out, pair_success…

label.update

WhatsApp Business labels: edits, association with chats and messages.

Full event catalog

Payload schemas, enums and examples for each of the 6 types.

​
Webhook vs WebSocket

AspectWebhookWebSocket
ProtocolHTTP POSTWS (TCP upgrade)
DeliveryAsync, persisted in queueReal-time, in memory
Retry/DLQExponential backoff 1s→1h, up to 5 attempts + DLQNo retry, events lost if client offline
Event filterevents[] per configevents[] per config
Base64 mediamediaBase64 optionalmediaBase64 optional
AuthenticationConfigurable Authorization headerToken on upgrade (header or ?token=)
HeartbeatN/APING/PONG ~54s/60s
LimitUp to 3 enabled webhooks per instance1 config per instance (broadcast to N connected clients)
BackpressureQueue grows in DB256-msg buffer per client; slow ones are dropped
Survives consumer crash?YesNo

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

​
Best practices

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

​
Next steps

Configure webhook

POST /api/events/webhook/:instance, creates/updates by label.

List webhooks

GET /api/events/getWebhook/:instance, all or by ?label=.

Configure WebSocket

POST /api/events/websocket/:instance, enabled, events, mediaBase64.

Check WebSocket config

GET /api/events/getWebsocket/:instance.

Event catalog

Schemas and examples for the 6 types.

Connect via WebSocket

GET /ws/:instance, protocol, auth, reconnection.