Вебхук событий: обращения, заявки и звонки AI-агента в вашу аналитику

Подключение

1. Личный кабинет → Настройки → Интеграции → «Вебхук событий».
2. Укажите https://-URL, скопируйте сгенерированный секрет, отметьте нужные события.
3. Нажмите «Проверить подключение» — придёт событие webhook.test, ответьте 2xx.
4. Сохраните. Дальше события идут автоматически; последние доставки и ошибки видны там же.

Требования к эндпоинту

• Только https://.
• Отвечать 2xx в пределах ~10 секунд. Обрабатывайте асинхронно — сначала ответьте, потом считайте.
• Идемпотентность по event_id — повтор доставки несёт тот же идентификатор.
• Ветвиться по event и отвечать 2xx на неизвестные типы (включая webhook.test).

Каталог событий

Подписка точная: приходят только отмеченные типы; новые типы, которые появятся в платформе позже, не включаются автоматически. Раскройте событие — внутри ровно тот JSON, который прилетит на ваш URL.

{
  "event": "lead.created",
  "event_id": "0b7e6c4a-2f1d-4e8b-9a3c-5d6e7f8a9b0c",
  "api_version": "1",
  "occurred_at": "2026-09-14T09:40:00Z",
  "sent_at": "2026-09-14T10:15:04.001Z",
  "organization_id": 2,
  "demo_mode": null,
  "channel": {
    "type": "telegram",
    "id": 12,
    "name": "Бот продаж"
  },
  "agent": {
    "id": 21,
    "name": "Фитнес — чат"
  },
  "contact": {
    "id": 7,
    "first_name": "Иван",
    "last_name": "Петров",
    "phone": null,
    "callback_phone": "+79995554433",
    "email": null,
    "telegram": "@ivan_petrov",
    "whatsapp": null,
    "channel_user_id": null,
    "channel_handle_label": null,
    "company": null,
    "role": "unknown",
    "channel": "telegram"
  },
  "lead": {
    "id": 461,
    "url": "https://salesworkshop.ai/leads/461",
    "type": "new",
    "status": "new",
    "mode": "ai",
    "is_hot": false,
    "goal_reached": false,
    "summary": null,
    "channel": "telegram",
    "call_resolution": null,
    "direction": "inbound",
    "click_id": "16234567890123456789",
    "click_source": "yandex",
    "start_param": "yclid_16234567890123456789",
    "created_at": "2026-09-14T09:40:00Z",
    "qualification": {
      "current_situation": null,
      "volume": null,
      "goals": null,
      "timeline": null,
      "budget_level": null
    },
    "custom_attributes": {}
  },
  "chat": {
    "id": 55
  },
  "actor": null,
  "data": {
    "message_id": 899,
    "content": "Новый лид создан",
    "lead_id": 461,
    "type": "new"
  }
}

{
  "event": "lead.handoff",
  "event_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "api_version": "1",
  "occurred_at": "2026-09-14T10:21:45Z",
  "sent_at": "2026-09-14T10:15:04.001Z",
  "organization_id": 2,
  "demo_mode": null,
  "channel": {
    "type": "telegram",
    "id": 12,
    "name": "Бот продаж"
  },
  "agent": {
    "id": 21,
    "name": "Фитнес — чат"
  },
  "contact": {
    "id": 7,
    "first_name": "Иван",
    "last_name": "Петров",
    "phone": null,
    "callback_phone": "+79995554433",
    "email": null,
    "telegram": "@ivan_petrov",
    "whatsapp": null,
    "channel_user_id": null,
    "channel_handle_label": null,
    "company": null,
    "role": "unknown",
    "channel": "telegram"
  },
  "lead": {
    "id": 461,
    "url": "https://salesworkshop.ai/leads/461",
    "type": "new",
    "status": "active",
    "mode": "manual",
    "is_hot": true,
    "goal_reached": false,
    "summary": "Интересует годовой абонемент, спрашивал про бассейн и рассрочку.",
    "channel": "telegram",
    "call_resolution": null,
    "direction": "inbound",
    "click_id": "16234567890123456789",
    "click_source": "yandex",
    "start_param": "yclid_16234567890123456789",
    "created_at": "2026-09-14T09:40:00Z",
    "qualification": {
      "current_situation": "Ходит в зал у дома, не устраивает оборудование",
      "volume": "Годовой абонемент, 1 человек",
      "goals": "Похудеть к лету, нужен бассейн",
      "timeline": "Готов купить на этой неделе",
      "budget_level": "до 40 000 ₽"
    },
    "custom_attributes": {
      "club": "Ленина"
    }
  },
  "chat": {
    "id": 55
  },
  "actor": {
    "type": "agent",
    "id": "21",
    "name": "Фитнес — чат"
  },
  "data": {
    "message_id": 910,
    "content": "AI запросил передачу менеджеру: ready_to_buy",
    "reason": "ready_to_buy",
    "from_mode": "ai",
    "to_mode": "manual"
  }
}

{
  "event": "call.ended",
  "event_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
  "api_version": "1",
  "occurred_at": "2026-09-14T11:04:51Z",
  "sent_at": "2026-09-14T10:15:04.001Z",
  "organization_id": 2,
  "demo_mode": null,
  "channel": {
    "type": "voice",
    "id": 3,
    "name": "Sipuni — офис"
  },
  "agent": {
    "id": 32,
    "name": "Фитнес — звонки"
  },
  "contact": {
    "id": 7,
    "first_name": "Иван",
    "last_name": "Петров",
    "phone": "+79991234567",
    "callback_phone": null,
    "email": null,
    "telegram": null,
    "whatsapp": null,
    "channel_user_id": null,
    "channel_handle_label": null,
    "company": null,
    "role": "unknown",
    "channel": "voice"
  },
  "lead": {
    "id": 462,
    "url": "https://salesworkshop.ai/leads/462",
    "type": "new",
    "status": "active",
    "mode": "ai",
    "is_hot": true,
    "goal_reached": false,
    "summary": "Позвонил узнать про абонемент, договорились о пробной тренировке в субботу.",
    "channel": "phone",
    "call_resolution": null,
    "direction": "inbound",
    "click_id": null,
    "click_source": null,
    "start_param": null,
    "created_at": "2026-09-14T09:40:00Z",
    "qualification": {
      "current_situation": "Ходит в зал у дома, не устраивает оборудование",
      "volume": "Годовой абонемент, 1 человек",
      "goals": "Похудеть к лету, нужен бассейн",
      "timeline": "Пробная тренировка в субботу",
      "budget_level": "до 40 000 ₽"
    },
    "custom_attributes": {
      "club": "Ленина"
    }
  },
  "chat": {
    "id": 56
  },
  "actor": {
    "type": "system",
    "id": null,
    "name": "Голосовой вызов"
  },
  "data": {
    "message_id": 1201,
    "content": "Голосовой вызов: Заинтересован (2:41)",
    "voice_call_id": "3f2a9c1e-7b4d-4e6a-9c8b-1d2e3f4a5b6c",
    "duration_seconds": 161,
    "outcome": "interested",
    "outcome_label": "Заинтересован",
    "transcript_count": 18,
    "direction": "inbound",
    "termination_reason": "USER_HANGUP",
    "termination_detail": null
  }
}

Ответы агента, отдельные сообщения и реплики звонка, смены статусов и служебные события ленты не публикуются — каталог расширяется по запросу. Ссылка на запись звонка наружу не передаётся.

Рекламные конверсии: «написал в мессенджер» с идентификатором клика

Событие lead.created приходит один раз на обращение — в момент первого сообщения клиента в мессенджере (или первого звонка), до ответа агента. Это и есть конверсия «написал в мессенджер»: не нужно дедуплицировать сообщения одного диалога. Чтобы связать её с кликом по объявлению, донесите идентификатор клика до бота.

1. Ведите рекламу на бота ссылкой с идентификатором клика в параметре start: https://t.me/<бот>?start=yclid_<yclid> (в MAX — https://max.ru/<бот>?start=yclid_<yclid>) для Яндекс Директа, gclid_… для Google Ads, fbclid_… для Meta, ttclid_… для TikTok, rb_clickid_… для VK. Рекламные сети подставляют клик только в адрес вашего сайта, поэтому обычно делают редирект: объявление ведёт на страницу сайта, она читает идентификатор из адреса и перенаправляет на ссылку бота с ним (в параметре допустимы только буквы, цифры, _ и -, до 64 символов).
2. В Telegram первое сообщение клиента приходит как /start yclid_…, в MAX параметр приходит при нажатии «Начать»; платформа сохраняет его на лиде: lead.click_id — сам идентификатор, lead.click_source — сеть по префиксу (yandex, google, meta, tiktok, vk), lead.start_param — сырое значение. Без префикса платформа не гадает: голое число, промокод или метка кампании сохраняются только в start_param, а click_id остаётся null. Первый клик выигрывает: повторные /start того же лида ничего не меняют. В MAX параметр приходит только при первом запуске бота — клиент, который уже писал боту раньше, придёт по рекламной ссылке без click_id.
3. Подпишитесь на lead.created, отфильтруйте channel.type (telegram, whatsapp_baileys, max — или voice, если первым был звонок) и загрузите конверсию в рекламный кабинет по lead.click_id и occurred_at. Без идентификатора клика остаётся сопоставление по contact.phone / contact.telegram через загрузку CRM-конверсий.

Как понять исход звонка

Типичная задача партнёра: сам звонок и запись он получает от своей телефонии, а от платформы нужен результат — перевёл ли агент на менеджера, договорился ли, квалифицировал ли сам. Подпишитесь на lead.created, call.ended и lead.handoff и читайте:

Сопоставление с записями вашей телефонии — по contact.phone (номер, с которого позвонили / который набрали) и времени: occurred_at у lead.created для первого звонка, occurred_at и data.duration_seconds у call.ended; data.voice_call_id — внутренний идентификатор платформы, не SIP Call-ID. Все события одного лида несут один lead.id; lead.handoff приходит через несколько секунд после call.ended.

Аутентификация

Каждый запрос несёт заголовок Authorization: Bearer <секрет>. Секрет (UUID) генерируется в личном кабинете при подключении. Сравнивайте его со своим константным по времени сравнением и отклоняйте запрос при несовпадении.

PHP

$expected = getenv('SWS_WEBHOOK_SECRET');
$header   = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$token    = preg_replace('/^Bearer\s+/i', '', $header);

if (!hash_equals($expected, $token)) {
    http_response_code(401);
    exit;
}

Node.js

const crypto = require("crypto");

function verify(req) {
  const expected = process.env.SWS_WEBHOOK_SECRET;
  const token = (req.headers.authorization || "").replace(/^Bearer\s+/i, "");
  const a = Buffer.from(token);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Заголовки

Тело запроса

Один JSON-объект: общий конверт + блоки channel, agent, contact, lead, chat, actor и data с полями конкретного события (примеры — в каталоге выше). Скалярные поля всегда присутствуют, null — если значение неизвестно. Блоки contact / lead / channel / agent отражают состояние на момент доставки (обычно секунды после события); сами переходы — в data.

Доставка, повторы, порядок

• Асинхронно, надёжно. Событие попадает в очередь платформы (PostgreSQL) прямо в базе, триггером, вместе с записью самого события; отдельный воркер отправляет его. Ни ответ агента, ни звонок не ждут ни доставки, ни постановки в очередь.
• Повторы. На сетевую ошибку, таймаут, 408, 429 или 5xx — экспоненциальный backoff от 30 секунд до 1 часа, до 8 попыток. На 3xx и прочие 4xx повтора нет — событие помечается ошибкой сразу (обычно это неверный секрет или URL).
• At-least-once. Повтор несёт тот же event_id и увеличенный X-SWS-Delivery — дедуплицируйте по event_id.
• Порядок не гарантируется. Сортируйте по occurred_at; события одного лида связывайте через lead.id.
• Что не приходит. События типов, на которые вы не подписаны; события за время, пока вебхук был на паузе или ещё не подключён; dry-тесты агента из «Превью».
• История последних доставок с HTTP-кодом, числом попыток и ошибкой видна в личном кабинете.

Тестовое событие webhook.test

При «Проверить подключение» платформа отправляет POST с теми же заголовками, но без блоков события. Отвечайте 2xx, ничего не создавая.

{
  "event": "webhook.test",
  "event_id": "d3c1a2b4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "api_version": "1",
  "occurred_at": "2026-09-14T10:00:00.000Z",
  "sent_at": "2026-09-14T10:00:00.000Z",
  "message": "Тестовое событие от Sales Workshop AI. Вебхук событий подключён."
}

Версионирование

api_version фиксирует версию контракта. В рамках версии изменения только аддитивные (новые типы событий, новые необязательные поля) — пишите приёмник устойчиво к ним.

Вопросы и ответы

Как передать конверсию «написал в мессенджер» в Яндекс Директ?

Подпишитесь на событие lead.created: оно приходит один раз на обращение и содержит lead.click_id — идентификатор клика из ссылки на бота вида t.me/<бот>?start=yclid_<yclid> (lead.click_source = yandex). Загрузите конверсию в Метрику или Директ по этому id.

Как узнать, что AI-агент перевёл звонок на менеджера?

В событии call.ended поле data.termination_reason равно TRANSFERRED, а в блоке lead поле call_resolution равно transferred.

Что делать, если событие пришло повторно?

Доставка at-least-once: повтор несёт тот же event_id и увеличенный X-SWS-Delivery. Дедуплицируйте по event_id и отвечайте 2xx.