API Reference
Webhooks
Real-time HTTPS POST notifications when messages arrive, delivery status changes, or Device/QR channels connect or disconnect.
How delivery works
- Transport — HTTPS POST with JSON body
- Queue — Asynchronous with automatic retries
- Timeout — 8s per attempt
- Retries — Up to 5 attempts with exponential backoff (60s → 5m → 15m → 1h → 2h)
- Auto-disable — After 10 consecutive failures the endpoint is disabled until re-enabled
Unified across channels
Cloud API and Device/QR share the same event names and payload format. Register once via
POST /v1/webhooks or the dashboard.
Events
Subscribe to one or more events per endpoint. Leave events empty or null to receive all events.
| Event | Channels | Description |
|---|---|---|
message.received |
cloud, device | A new inbound message was received (Cloud API or Device/QR channel). |
message.sent |
cloud, device | An outbound message was accepted and sent from your account. |
message.delivered |
cloud, device | An outbound message was delivered to the recipient device. |
message.read |
cloud, device | An outbound message was read by the recipient. |
message.failed |
cloud, device | An outbound message failed to send or deliver. |
device.connected |
device | A Device/QR channel connected successfully (WhatsApp linked). |
device.disconnected |
device | A Device/QR channel lost its WhatsApp connection. |
device.status_changed |
cloud, device | Any channel connection-status transition (payload includes from_status and to_status). Fired in addition to device.connected/device.disconnected. |
Request envelope
JSON
{
"event": "message.received",
"timestamp": "2026-07-10T12:00:00+03:00",
"data": { }
}| Field | Type | Description |
|---|---|---|
event | string | Event name from the table above |
timestamp | ISO 8601 | When Washeej generated this delivery |
data | object | Event payload — structure depends on event type |
Real-time vs webhooks
| Mechanism | Audience | Use case |
|---|---|---|
| Webhooks | Your server | Message events, delivery status, device connection |
| Pusher (WebSocket) | Washeej web inbox only | Live UI updates — not part of the public API |