Уведомления по API: заявки и сигналы бота на ваш сервер

Какие уведомления приходят

События о токенах относятся ко всему балансу аккаунта, а не к одному боту, поэтому приходят на адреса всех ботов, где подключён API. Если у нескольких ботов один адрес, придёт один запрос.

Как подключить

1. 1

   Откройте уведомления бота

   Первая линия → Боты, выберите бота, вкладка «Уведомления». В строке API нажмите «Настройте уведомления».

2. 2

   Вставьте адрес приёмника

   В поле «Адрес приёмника (URL)» укажите адрес, который будет принимать POST-запросы: эндпоинт вашей CRM, webhook-триггер Make или n8n, Catch Hook в Zapier. Адрес должен начинаться с https://.

3. 3

   Нажмите «Тест»

   На адрес уйдёт пример заявки с событием test. Под кнопкой появится код ответа, время и начало ответа вашего сервера. Код 2xx — всё работает. Сохранять адрес перед тестом не нужно.

   Тест можно запускать не чаще 5 раз в минуту для одного бота — так настройка не превратится в поток запросов к чужому серверу.

4. 4

   Сохраните

   Нажмите «Сохранить» — строка API в списке уведомлений станет «Уведомления настроены». Отключить отправку можно кнопкой «Отключить» в той же модалке.

Принимаются только адреса https. Внутренние и локальные адреса (localhost, 10.x, 192.168.x и т. п.) не принимаются — приёмник должен быть доступен из интернета.

Формат запроса

Метод POST, тело — JSON в UTF-8. Тип уведомления — в поле event и в заголовке X-Webhook-Event. Поле type оставлено для совместимости со старыми интеграциями (lead_new, lead_update, bot_chat_have_mistake, tokens_threshold, tokens_depleted, bot_reply_no_balance, lead_test).

Заявка: lead.created и lead.updated

{
  "event": "lead.created",
  "type": "lead_new",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "lead": {
      "id": "9b2f6c1e-…",
      "name": "Анна",
      "phone": "+79991234567",
      "email": "anna@example.ru",
      "telegram_username": null,
      "city": "Казань",
      "address": null,
      "scheduled_call": null,
      "type_payment": null,
      "need_delivery": null,
      "delivery_time": null,
      "meeting_date_time_office": null,
      "meeting_date_time_client": null,
      "extended_info": null,
      "status": "NEW",
      "comment": "Нужен расчёт на 3 комнаты"
    },
    "botChatId": 12345,
    "shortInfo": "Клиентка хочет ремонт трёх комнат, просит перезвонить вечером",
    "messages": "Клиент: …\nБот: …",
    "linkToChat": "https://…",
    "channelUrl": "https://…"
  },
  "timestamp": "2026-09-21T12:00:00.000Z",
  "delivery_id": "3f1c2a4e-…"
}

• data.lead.id одинаковый у lead.created и всех lead.updated одной заявки — по нему обновляйте запись у себя.
• Поля, которые бот не собрал, приходят как null.
• shortInfo — выжимка диалога, messages — текст переписки: краткий или полный в зависимости от настройки бота «Как формировать уведомление в Telegram?».
• linkToChat — ссылка на диалог в исходном канале, если площадка её даёт.

Боту нужна помощь: chat.help_needed

{
  "event": "chat.help_needed",
  "type": "bot_chat_have_mistake",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "reason": "bot_asked",
    "botId": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "botChatId": 12345,
    "shortInfo": "Клиент спрашивает про нестандартный заказ",
    "messages": "Клиент: …\nБот: …",
    "linkToChat": "https://…"
  },
  "timestamp": "2026-09-21T12:05:00.000Z",
  "delivery_id": "…"
}

Бот в этом чате уже остановился и ждёт человека: откройте диалог по linkToChat или в разделе Чаты и ответьте клиенту сами.

Баланс токенов: tokens.*

{
  "event": "tokens.low",
  "type": "tokens_threshold",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "bot_ids": [
    "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "5e0a7d31-…"
  ],
  "data": {
    "tokensRemaining": 50000
  },
  "timestamp": "2026-09-21T13:00:00.000Z",
  "delivery_id": "…"
}

События о токенах приходят один раз на адрес: в bot_ids — все боты с этим адресом, в bot_id — бот, чьим секретом подписан запрос. Используйте tokens.low, чтобы вовремя пополнить баланс, а tokens.depleted и tokens.bot_silent — как тревогу: клиенты остаются без ответа.

Проверка подписи

Секрет подписи показан в той же модалке, в блоке «Секрет подписи» (кнопки «Показать» и «Копировать»). У каждого бота свой секрет. Подпись считается так: HMAC-SHA256 от строки X-Webhook-Timestamp + . + сырое тело запроса, ключ — секрет, результат в hex с префиксом sha256=. Считайте её по телу до разбора JSON: после повторной сериализации строка может не совпасть.

import crypto from "node:crypto";

// rawBody — тело запроса строкой, ДО JSON.parse
function isValid(rawBody, headers, secret) {
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(headers["x-webhook-timestamp"] + "." + rawBody)
      .digest("hex");
  const got = headers["x-webhook-signature"] || "";
  return (
    got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
  );
}

<?php
$rawBody   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret    = 'whsec_…'; // секрет из настроек бота

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// … сохранить заявку по $event['data']['lead']['id']
http_response_code(200);

Чтобы отсечь повтор старого запроса, сравнивайте X-Webhook-Timestamp с текущим временем (например, не старше 5 минут) и храните обработанные delivery_id.

Если секрет утёк, нажмите «Выпустить новый»: старый перестанет работать сразу, поэтому обновите его на своём сервере.

Доставка и ответ сервера

• Ответьте кодом 2xx в течение 10 секунд. Тяжёлую обработку делайте после ответа, в фоне.
• Редиректы не выполняются — укажите конечный адрес.
• Повторов при ошибке нет. Уведомление по API не придёт, но остальные каналы (Telegram, MAX, почта, CRM) сработают, а заявка сохранится в разделе Заявки.
• API работает вместе с остальными каналами, а не вместо них: можно одновременно получать заявки в Telegram и в свою систему.