Outbound webhooks

Moveo delivers bot responses, agent messages, and session events to your webhook endpoint via HTTP POST requests.

Webhook request format

All webhook requests include the following headers:

Header	Description
Content-Type	application/json
X-Moveo-Signature	HMAC-SHA256 signature of the request body.

Every webhook payload contains these base fields:

{
  "event_type": "message:brain_send",
  "request_id": "req-123",
  "session_id": "sess-456",
  "external_session_id": "your-session-789",
  "integration_id": "intg-001",
  "desk_id": "desk-456",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1704067200000
}

Field	Type	Description
event_type	string	Type of event. See event types.
request_id	string	Unique identifier for this request.
session_id	string	Moveo's internal session ID.
external_session_id	string	Your session ID, if provided during session creation.
integration_id	string	The integration ID associated with this session.
desk_id	string	The desk ID associated with this session.
context	object	Session context object, if available. See sessions for the context schema.
timestamp	integer	Event creation time as a Unix timestamp in milliseconds.

---

Event types

Event type	Description
message:brain_send	AI agent sends a message to the user.
message:send	Moveo live chat agent sends a message to the user.
message:compose	Typing indicator (start/stop).
message:read	Messages marked as read.
message:delivered	Messages marked as delivered.
conversation:member_join	Agent joined the conversation.
conversation:member_leave	Agent left the conversation.
conversation:closed	Conversation marked as resolved.
conversation:reopened	Conversation reopened.
session:closed	Session closed.
session:expired	Session expired due to timeout.

For detailed payload schemas of each event type, see event payloads.

---

Event subscription

You can filter which events you receive by configuring subscribed_events during integration setup.

Example: Only receive bot and agent messages.

{
  "subscribed_events": ["message:brain_send", "message:send"]
}

If subscribed_events is empty or not set, you receive all event types.

---

Next steps

• Event payloads — detailed schemas for all event types.
• Webhook security — verify webhook signatures and handle responses.
• Error handling — error codes, troubleshooting, and limitations.