Overview
WhatsRB Cloud sends HTTP POST requests to your configured endpoint when events occur. Register an endpoint via the API or the dashboard.
Supported events
| Event | Description |
|---|
message.received | An inbound message was received |
message.status | A message status changed (sent, delivered, read) |
message.failed | A message failed to send |
session.connected | A WhatsApp Web session connected |
session.disconnected | A WhatsApp Web session disconnected |
session.failed | A session connection failed |
quota.warning | Approaching your daily message quota |
quota.exceeded | Daily message quota exceeded |
{
"event": "message.status",
"data": { ... },
"timestamp": "2026-01-01T12:00:00Z"
}
data object content varies by event type.
Signature verification
Every request includes two headers:
X-Webhook-Signature — HMAC-SHA256 signature with sha256= prefixX-Webhook-Event — the event name
The signature format is:
sha256=<HMAC-SHA256(secret, raw_body)>
Verify with the Ruby SDK
valid = WhatsrbCloud::WebhookSignature.verify?(
payload: request.body.read,
signature: request.headers["X-Webhook-Signature"],
secret: ENV["WHATSRB_WEBHOOK_SECRET"]
)
return head :unauthorized unless valid
Verify manually (any language)
expected = "sha256=" + HMAC_SHA256(webhook_secret, raw_request_body)
secure_compare(expected, X-Webhook-Signature header)
Always use a constant-time string comparison to prevent timing attacks.
Getting your webhook secret
The secret is returned once when you create the endpoint:
{
"data": {
"id": 1,
"url": "https://yourapp.com/webhooks",
"secret": "whsec_xxxxxxxxxxxx"
}
}
