Вебхуки: настройка и события

Вебхуки

Вебхуки позволяют Chatonio уведомлять ваш сервер о событиях в проекте — чаще всего это уведомление о новом сообщении клиента. Chatonio отправляет подписанный POST с телом JSON на указанный вами URL.

API-ключ для вебхуков не нужен. Добавляйте и настраивайте эндпоинты на странице Developer вашего проекта (ими также можно управлять через API).

Настройка эндпоинта

• Откройте Настройки проекта → Developer → Вебхуки и нажмите Добавить вебхук.
• Укажите ваш HTTPS-URL и отметьте нужные события.
• Скопируйте секрет подписи, показываемый один раз при создании — он нужен для проверки доставок (см. Проверка вебхуков и надёжность).

Ваш эндпоинт должен быстро отвечать статусом 2xx. Реальную обработку выполняйте асинхронно.

Разрешение нашего IP

Все доставки вебхуков уходят из Chatonio с одного фиксированного адреса:

• 64.7.198.218

Если ваш эндпоинт находится за файрволом, WAF или списком разрешённых IP — добавьте этот адрес. Он стабилен, о любом изменении мы сообщим здесь заранее.

Список разрешённых IP не заменяет проверку подписи. Он подтверждает лишь то, что запрос пришёл из нашей сети, но не то, что отправили его мы — это доказывает только заголовок Chatonio-Signature. См. Проверка вебхуков и надёжность.

События

• message.created — в диалог добавлено сообщение (любой отправитель, кроме внутренних заметок). Для «нового сообщения клиента» фильтруйте по data.message.sender_type == "CLIENT".
• conversation.created — создан новый диалог.
• conversation.status_changed — у диалога изменился статус.

Формат payload

У каждой доставки одинаковый конверт: уникальный id, тип события type, api_version, метка времени created и объект data, специфичный для события.

message.created

{
  "id": "d5e1a220-4f77-4c33-a1b2-c3d4e5f60718",
  "type": "message.created",
  "api_version": "v1",
  "created": "2026-07-01T10:30:00+00:00",
  "data": {
    "message": {
      "id": "a1000000-0000-4000-8000-000000000001",
      "conversation_id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "sender_type": "CLIENT",
      "content": "Where is my order?",
      "is_internal_note": false,
      "thread_id": null,
      "created_at": "2026-07-01T10:30:00+00:00"
    },
    "conversation": {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "NEW",
      "channel_id": "9a1c5f30-2b6d-4c71-8e42-1a2b3c4d5e6f",
      "channel_type": "WEB"
    }
  }
}

conversation.created

{
  "id": "d5e1a220-4f77-4c33-a1b2-c3d4e5f60719",
  "type": "conversation.created",
  "api_version": "v1",
  "created": "2026-07-01T10:29:00+00:00",
  "data": {
    "conversation": {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "NEW",
      "subject": "",
      "source": "CHANNEL",
      "channel_id": "9a1c5f30-2b6d-4c71-8e42-1a2b3c4d5e6f",
      "channel_type": "WEB",
      "ticket_number": null,
      "created_at": "2026-07-01T10:29:00+00:00"
    }
  }
}

conversation.assigned

Диалог назначен оператору или снят с него. Одно событие покрывает оба направления: при снятии operator равен null. Событие срабатывает независимо от того, как произошло изменение — оператор взял диалог в дашборде, сработала автомаршрутизация или вы вызвали API.

{
  "id": "9a3f7c11-2b60-4d5e-8f09-1a2b3c4d5e6f",
  "type": "conversation.assigned",
  "api_version": "v1",
  "created": "2026-07-01T10:46:00+00:00",
  "data": {
    "conversation": {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "PROCESSING"
    },
    "operator": { "user_id": "7c1e5a02-9b43-4f18-8a77-2d6e0f4b9c81" }
  }
}

conversation.status_changed

{
  "id": "d5e1a220-4f77-4c33-a1b2-c3d4e5f60720",
  "type": "conversation.status_changed",
  "api_version": "v1",
  "created": "2026-07-01T10:45:00+00:00",
  "data": {
    "conversation": {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "RESOLVED",
      "previous_status": "PROCESSING"
    }
  }
}

message.created срабатывает для каждого сообщения — клиента, оператора, ИИ и системных уведомлений. Внутренние заметки операторов вебхуками не отправляются, поэтому в доставленных событиях поле is_internal_note всегда false. Используйте sender_type, чтобы оставить только нужное.