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

Вебхуки

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

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

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

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

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

События

• 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.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 срабатывает для каждого сообщения — клиента, оператора, ИИ и системных уведомлений. Используйте sender_type, чтобы оставить только нужное.