Message sent

Incoming webhook deliveries are authenticated with HMAC signature headers (X-Chatway-Signature and X-Chatway-Timestamp), not your Chatway API key.

An agent sent a new message.

Triggered when an agent sends a message from the dashboard or API (including POST /messages).

Internal notes, reminders, and system messages are not included.

data.agent is always present on this event. Dashboard sends use the signed-in agent. API sends use the agent_id on the stored message (include agent_id in POST /messages for agent-originated replies).

POST webhook: message.sent

Parameters

Name	In	Required	Type	Description
`X-Chatway-Event`	header	Yes	string	Event name for this delivery. Example: message.sent
`X-Chatway-Webhook-Id`	header	Yes	string (uuid)	Unique webhook subscription ID. Example: 9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b
`X-Chatway-Delivery-Id`	header	Yes	string	Unique ID for this HTTP delivery attempt (`del_…`). Example: del_456
`X-Chatway-Delivery-Attempt`	header	Yes	string	Attempt number for this event (`1` on first try). Sent as a decimal string in the header. Example: 1
`X-Chatway-Timestamp`	header	Yes	string	Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header. Example: 1785933000
`X-Chatway-Signature`	header	Yes	string	HMAC SHA256 signature prefixed with `sha256=`. Example: sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4

Request body

Signed JSON envelope for this event.

application/json

id (string, required) — Stable event ID (`evt_…`). Same across HTTP retries for this notification.
event (string, required) — Event name. For this webhook, always `message.sent`.
data (object, required) — Payload for message.sent.
- message (object, required)
  - id (string, required) — Message ID.
  - content (string) — Message text. May be omitted when attachments are present.
  - attachments (array<object>, required) — Zero or more attachment objects. Each item has `content` (URL), optional `type`, `mime`, `original_file_name`, and `size` (bytes)—see Webhooks overview → Field reference → Attachment.
    - content (string, required) — Public URL of the file (up to 2048 characters).
    - type (string) — Logical type (for example image, file, video).
    - mime (string) — MIME type when known.
    - original_file_name (string) — Original filename when available.
    - size (integer|null) — Size in bytes when known.
  - created_at (string (date-time), required) — When the message was created.
- conversation (object, required)
  - id (string (uuid), required) — Conversation ID.
  - channel (string, required) — Normalized channel.
  - status (string, required) — Conversation status.
  - widget_name (string) — Present when the conversation is tied to a website widget.
  - identifier (string) — Widget identifier when widget_name is present.
- visitor (object, required)
  - id (string (uuid), required) — Visitor/contact ID.
  - name (string) — Visitor name. Omitted when empty.
  - email (string|null, required) — Visitor email. Always present; null when unknown.
  - phone (string|null, required) — Visitor phone. Always present; null when unknown.
- agent (object, required) — Agent who sent the message. Always present on message.sent (dashboard agent or POST /messages `agent_id`).
  - id (string (uuid), required) — Agent ID.
  - name (string, required) — Agent display name.
  - email (string) — Agent email when available.
occurred_at (string (date-time), required) — When the business event occurred.
version (string, required) — Payload schema version.

Responses

200

Return any 2xx status to acknowledge receipt.

410

Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop.

Examples

Request body example

{
    "id": "evt_1234567890abcdef1234567890abcdef",
    "event": "message.sent",
    "data": {
        "message": {
            "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
            "content": "Happy to help! Let me look into that for you.",
            "attachments": [],
            "created_at": "2026-02-04T10:32:00Z"
        },
        "conversation": {
            "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023",
            "channel": "website",
            "status": "open",
            "widget_name": "Main site widget",
            "identifier": "wdg_abc123"
        },
        "visitor": {
            "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702",
            "name": "John Doe",
            "email": "[email protected]",
            "phone": "+1XXXXXXXXXX"
        },
        "agent": {
            "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a",
            "name": "Sarah Chen",
            "email": "[email protected]"
        }
    },
    "occurred_at": "2026-02-04T10:32:00Z",
    "version": "2026-09"
}