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 exact names (message.received) and/or families (message.*, device.*). Leave events empty or null to receive all events. There is no message.created event — inbound is message.received.
| Event | Channels | Description |
|---|---|---|
message.* |
cloud, device | Family wildcard — matches message.received, message.sent, message.delivered, message.read, and message.failed. |
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.* |
device, cloud | Family wildcard — matches device.connected, device.disconnected, and device.status_changed. |
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. |
ticket.created |
cloud, device | A tenant ticket was created. |
ticket.updated |
cloud, device | A tenant ticket was updated. |
ticket.closed |
cloud, device | A tenant ticket was closed. |
ticket.reopened |
cloud, device | A tenant ticket was reopened. |
ticket.csat |
cloud, device | A CSAT score was recorded on a tenant ticket. |
template.created |
cloud | A Meta template was created and submitted. |
template.submitted |
cloud | A Meta template was submitted for review. |
template.status.updated |
cloud | Meta updated a template status. |
template.rejected |
cloud | Meta rejected a template. |
template.approved |
cloud | Meta approved a template. |
template.deleted |
cloud | A Meta template was deleted. |
template.sync.failed |
cloud | Template sync with Meta failed. |
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 |