Webhooks

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
`agent_run.completed`	An agent run completed successfully
`agent_run.actioned`	Sent when all actions on a confirmation-mode run have been decided (confirmed, rejected, or expired)
`agent_run.failed`	An agent run failed
`conversation.paused`	A conversation was paused (human takeover)
`conversation.resumed`	A conversation pause was manually resumed
`quota.warning`	Approaching your daily message quota
`quota.exceeded`	Daily message quota exceeded

Payload format

{
  "event": "message.status",
  "data": { ... },
  "timestamp": "2026-01-01T12:00:00Z"
}

The data object content varies by event type — see below for each event.

`message.received` payload

Fired when an inbound message is received on any channel.

Common fields

Field	Type	Description
`id`	String	WhatsRB message ID (`wrb_msg_...`)
`wamid`	String	WhatsApp message ID
`from`	String	Sender phone number
`type`	String	Message type (see below)
`content`	String	Human-readable content
`metadata`	Object	Structured data for rich message types (see below)
`channel`	String	`"business"`
`timestamp`	String	ISO 8601 timestamp

Supported message types

Type	`content`	`metadata`
`text`	Message body	`{}`
`image`	Media ID	`{}`
`video`	Media ID	`{}`
`audio`	Media ID	`{}`
`document`	Media ID	`{}`
`sticker`	Media ID	`{}`
`location`	`"lat,lng"`	`{}`
`contact`	Contact name	`{}`
`reaction`	Emoji (`"👍"`)	`{ "message_id": "wamid...", "emoji": "👍" }`
`interactive`	Button/list title	See interactive metadata
`order`	`"2x SKU123, 1x SKU456"`	`{ "product_items": [...] }`
`system`	`"system:group_created"`	Full system event object

Interactive metadata

When a user taps a button or selects a list item from a template, the message type is interactive. The metadata object contains:

Field	Type	Description
`interactive_type`	String	`"button_reply"`, `"list_reply"`, or `"nfm_reply"`
`button_reply` / `list_reply`	Object	Contains `id` and `title` of the selected option
`context_message_id`	String	wamid of the original template message (if present)

Example — button reply:

{
  "event": "message.received",
  "data": {
    "id": "wrb_msg_a1b2c3d4e5f6",
    "wamid": "wamid.HBg...",
    "from": "33612345678",
    "type": "interactive",
    "content": "Yes, confirm",
    "metadata": {
      "interactive_type": "button_reply",
      "id": "btn_confirm",
      "title": "Yes, confirm",
      "context_message_id": "wamid.HBg..."
    },
    "channel": "business",
    "timestamp": "2026-03-02T10:30:00Z"
  },
  "timestamp": "2026-03-02T10:30:00Z"
}

Example — list reply:

{
  "event": "message.received",
  "data": {
    "id": "wrb_msg_f6e5d4c3b2a1",
    "wamid": "wamid.HBg...",
    "from": "33612345678",
    "type": "interactive",
    "content": "Premium Plan",
    "metadata": {
      "interactive_type": "list_reply",
      "id": "plan_premium",
      "title": "Premium Plan",
      "description": "Unlimited messages, priority support",
      "context_message_id": "wamid.HBg..."
    },
    "channel": "business",
    "timestamp": "2026-03-02T10:30:00Z"
  },
  "timestamp": "2026-03-02T10:30:00Z"
}

Handling interactive replies

Route by metadata.interactive_type and use the option id (not title) for reliable matching:

case data["metadata"]["interactive_type"]
when "button_reply"
  handle_button(data["metadata"]["id"])
when "list_reply"
  handle_list(data["metadata"]["id"])
when "nfm_reply"
  handle_flow(data["metadata"])
end

The content field always contains a human-readable string, even for rich message types. Use it for display, use metadata for logic.

Message edits

When a user edits a message, WhatsRB updates the original message’s content in place. No message.received event is fired — the edit is silent.

Unsupported messages

Messages with type unsupported (e.g. polls) are silently ignored and do not trigger a webhook.

`agent_run.completed` payload

Fired when an AI agent completes processing an inbound message.

Field	Type	Description
`run_id`	String	Unique agent run ID (`run_...`)
`agent_id`	String	Agent ID (`agt_...`)
`status`	String	`"completed"`
`triggered_by`	String	`"auto_inbound"`, `"playground"`, or `"manual"`
`from`	String	Sender phone number (without `+`), `null` for playground runs
`metadata`	Object	Run metadata (conversation_key, pre_filter info)
`output`	Object	Agent output (intent, actions, suggested_reply, language)
`tokens`	Object	Token usage (`{ input, output }`)
`latency_ms`	Integer	LLM call latency
`duration_ms`	Integer	Total run duration

{
  "event": "agent_run.completed",
  "data": {
    "run_id": "run_abc123",
    "agent_id": "agt_def456",
    "status": "completed",
    "triggered_by": "auto_inbound",
    "from": "33612345678",
    "metadata": {
      "conversation_key": "2:33612345678"
    },
    "output": {
      "intent": "service request",
      "confidence": 0.9,
      "actions": [
        {
          "type": "operations.task.create",
          "payload": {
            "room_number": "204",
            "description": "Towel request",
            "category": "housekeeping",
            "priority": "medium"
          }
        }
      ],
      "language": "fr",
      "suggested_reply": "We'll bring towels to room 204.",
      "analysis_summary": "Guest requests towels for room 204."
    },
    "tokens": { "input": 564, "output": 191 },
    "latency_ms": 3600,
    "duration_ms": 3634
  },
  "timestamp": "2026-03-06T17:29:28Z"
}

Use the from field to match the sender to a user in your system. Use run_id for idempotent processing — webhook deliveries are at-least-once.

Signature verification

Every request includes two headers:

X-Webhook-Signature — HMAC-SHA256 signature with sha256= prefix
X-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"
  }
}

Store it securely — it cannot be retrieved again.

Getting Started

Core Concepts

Widget

Agent & Workflows

Overview

Supported events

Payload format

`message.received` payload

Common fields

Supported message types

Interactive metadata

Handling interactive replies

Message edits

Unsupported messages

`agent_run.completed` payload

Signature verification

Verify with the Ruby SDK

Verify manually (any language)

Getting your webhook secret

​Overview

​Supported events

​Payload format

​message.received payload

​Common fields

​Supported message types

​Interactive metadata

​Handling interactive replies

​Message edits

​Unsupported messages

​agent_run.completed payload

​Signature verification

​Verify with the Ruby SDK

​Verify manually (any language)

​Getting your webhook secret

Overview

Supported events

Payload format

`message.received` payload

Common fields

Supported message types

Interactive metadata

Handling interactive replies

Message edits

Unsupported messages

`agent_run.completed` payload

Signature verification

Verify with the Ruby SDK

Verify manually (any language)

Getting your webhook secret