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. See webhook security.
X-Moveo-Region	Cluster of the Moveo deployment that sent the event, for example eu-central.
X-Moveo-Account-Id	The account the event belongs to.
X-Moveo-Account-Slug	Human-readable name of that account.
X-Moveo-Session-Id	The session the event belongs to.
X-Moveo-Request-Id	Correlation identifier for this delivery.

Every header except Content-Type, X-Moveo-Signature, and X-Moveo-Region is omitted when Moveo does not know the value. Treat a missing header as unknown, not as an error.

Do not authorize on headers

Use these headers for logging and routing only. The signature covers the request body, not the headers, so a caller can forge them. Every header value above also appears as a field in the body — verify the signature, then read the value from the body, where it is trustworthy.

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",
  "channel_type": "chat",
  "account_id": "acc-123",
  "account_slug": "acme-co",
  "context": {
    "user": {
      "user_id": "user-789"
    }
  },
  "timestamp": 1789084800000
}

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.
channel_type	string	The session's channel type: chat, email, or voice.
account_id	string	The Moveo account this event belongs to. Always present.
account_slug	string	Human-readable name of that account. Always present.
context	object	Session context object, if available. See sessions for the context schema.
timestamp	integer	Event creation time as a Unix timestamp in milliseconds.

account_id and account_slug are covered by the signature, so they are safe to use for deciding which tenant's data an event belongs to. When Moveo cannot determine the account, both are an empty string — treat that as unknown and reject the event rather than routing on it.

external_session_id, integration_id, desk_id, channel_type, and context are omitted when the value is unavailable. timestamp carries the original event creation time and is absent on events that have no payload of their own, namely conversation:reopened and session:expired.

---

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.