Интеграции: вебхуки наружу и внутрь

Слово «вебхук» в разговорах про интеграции означает две разные вещи, и их постоянно путают. Внутрь: внешний сервис стучится в вашу CRM и запускает воронку. Наружу: CRM сама отправляет данные в чужой сервис — из блока воронки или потоком событий. Если сразу понять, в какую сторону идут данные, половина вопросов «почему не работает» снимается до того, как их зададут.

Где что лежит

Раздел «Интеграции и оплата» в группе «Настройки» открыт только администратору школы. Вкладки:

• «Эквайринг» открывается первой: платёжки, товары и оплаты. Как это устроено — «Приём оплат: эквайринг и ссылки на оплату».
• «Телефония» — своя АТС школы. Вкладка есть, когда подключён модуль «Отдел продаж».
• «Озвучка» — ключ ElevenLabs для голосовых из текста. Вкладка есть, если школе доступна озвучка.
• «Вебхуки» — адрес и токен, по которым внешний сервис запускает воронку, и приём анкеты с сайта.
• «Отправка событий» — адреса, куда CRM сама шлёт события воронок, оплат и сделок.
• «Прочее» — аккаунты GetCourse и SMSC, если они доступны школе.

Входов внутрь три: общий вебхук событий на вкладке «Вебхуки», анкета с сайта там же и свой адрес у старта «Вебхук (любой сервис)» прямо в воронке. Выходов наружу два: действие «Вебхук» в блоке «Действия» и вкладка «Отправка событий». Следствие простое: «внешний сервис не запускает воронку» разбирают во входах и в стартовом блоке, «данные не доходят до аналитики» — в действии «Вебхук», его прогонах или в журнале доставок.

12345

1. Вкладки раздела
2. «Запуск сценариев из внешнего сервиса»: состояние токенов и требования к запросу
3. Карточка вебхука: метод и путь, «Копировать URL», ниже полный адрес, заголовок и токен
4. «Заголовки одним блоком» — готовый JSON для вставки во внешний сервис; ниже свёрнутые «Поля запроса и пример» и строка «Ответ:»
5. Ниже — «Анкета с сайта» со своим адресом

Пока строка красная, вторую сторону настраивать бесполезно

Вкладка «Вебхуки» начинается с карточки «Запуск сценариев из внешнего сервиса» и одной из двух строк: «Токены вебхуков настроены» или «Токены вебхуков не настроены — запросы будут отклоняться». Вторая означает ровно это: внешний сервис получит отказ на каждый вызов. Токен руками не заводится, его выдаёт платформа. Поэтому сначала строка зелёная, потом настройка на той стороне.

Каждый адрес описан карточкой: метод и путь, кнопка «Копировать URL», назначение, затем «Полный URL», «Заголовок» и «Токен» со своими кнопками «Копировать». Ниже — «Заголовки одним блоком», свёрнутые «Поля запроса и пример» и строка «Ответ:».

Внутрь: одно событие на все случаи

Общий вход — POST на /webhooks/event (полный адрес берите кнопкой, он свой у каждой школы). Тело — JSON, токен — в заголовке X-Event-Token.

• event_key — обязателен. Ключ события: именно он связывает вызов с воронкой.
• lead — обязателен. Кому событие: tg_id, username или lead_key. Ник ищется без учёта регистра, с «@» и без. По телефону этот вход человека не находит.
• vars — необязателен. Любые поля события: они доступны в условии запуска и подставляются в тексты. Телефон из phone или «телефон» ляжет в карточку клиента, если там пусто.
• event_id — необязателен. Номер события, например номер заказа: по нему CRM узнаёт повторную доставку того же события.

{
  "event_key": "payment_ok",
  "lead": { "lead_key": "lead-123" },
  "vars": { "amount": 1000 },
  "event_id": "order-5521"
}

Мысль, на которой спотыкаются все: идентификатор в теле — способ найти человека, а не адрес доставки. Куда уйдёт первое сообщение — в бот, в личку или в групповой чат, — решает поле «Где вести воронку» в стартовом блоке.

Что означает ответ

На каждый вызов приходит { status, event_key, binding_id, run_started, run_id, repeat }. Смотреть надо не на код ответа, а на run_started.

Тот же след виден и в CRM: в переписке клиента администратор увидит строку «Колбек · событие „payment_ok“» с пришедшими полями, а если воронка не поехала — с припиской «воронка не запустилась» или «повтор, уже было».

Связь ключа с воронкой

Со стороны CRM вызов принимает стартовый блок: «Что запускает воронку» → «Внешнее событие (вебхук)» и поле с ключом события. Совпадение — буква в букву: payment_ok и Payment_OK разные ключи. Сам старт разобран в «Триггеры: чем запускается воронка», для интеграции важны три следствия:

• Воронка должна быть включена. Выключенная событие не поймает, а вызов ответит без ошибки — самый частый run_started: false.
• Группа «Повторный запуск» в старте. По умолчанию у внешнего события стоит «Только один раз»: событие запускает воронку у человека однажды. «При каждом событии» — каждое событие новый запуск: вторая оплата, второй приглашённый друг. Повтор того же события отсекается по event_id, а без него — одинаковое событие в течение 10 минут. Есть и «Не чаще, чем раз в …». У системных событий CRM — оплат, доступа к курсу, заявки в чат — «один раз» не бывает.
• Служебному событию вроде «оплата дошла» нужен переключатель «Не состояние»: обычный запуск останавливает активные воронки клиента, и платёж собьёт человека с прогрева.

Свой адрес у воронки: старт «Вебхук (любой сервис)»

Общему входу нужен токен в заголовке и тело в его формате. Форма Tilda, платёжка или CRM школы так часто не умеют. Для них в стартовом блоке есть «Вебхук (любой сервис)»: после сохранения листа у старта появляется своё поле «Адрес вебхука». Сервис шлёт туда GET или POST — JSON, форму или параметры в адресе, — и поля тела становятся переменными воронки: {name}, {tarif}, всё тело целиком — {вебхук_тело}.

• «Кого запускает»: «Без человека» — каждый вызов идёт своим прогоном: вычисления, вебхук в другой сервис, «Создать заявку», «Ответ странице», но писать человеку нельзя. «Человека из CRM» — человек ищется по tg_id, lead_key, телефону, почте или нику из тела, дальше обычная воронка.
• «Ждать ответа сценария» — сервис ждёт до 8 секунд и получает в поле reply то, что вернуло действие «Ответ странице»: цену, ссылку на оплату, номер заявки.
• «Последние вызовы» — что пришло и что запустилось. Первая проверка, когда «сервис говорит, что отправил».

Анкета с сайта без воронки

Вторая карточка вкладки «Вебхуки» — «Анкета с сайта», POST на /webhooks/anketa с тем же заголовком X-Event-Token. Форма присылает ответы «вопрос → ответ», а CRM кладёт их в переписку примечанием «Анкета», ставит групповому чату этап «Сдал анкету» и записывает телефон в карточку. Воронку собирать не нужно. Чтобы CRM узнала человека, добавьте в ссылку на анкету его id: …/anketa?tg_id={tg_id} — воронка подставит его сама, а форма вернёт в lead.tg_id. Если форма умеет только событие с переменными, возьмите готовую воронку: «Сценарии» → «Шаблоны» → «Анкета с сайта».

Наружу: из блока или потоком

Действие «Вебхук» в воронке

Адрес, метод, тело, заголовки и поле «Сохранить ответ». Как его заполнять — в «Блок «Действия»: этапы, вебхук, событие, команда, переходы, A/B». Для интеграции важно, когда придут данные.

Если сервис отвечает прямо в теле, переменная появляется сразу. Если он отвечает отдельным вызовом к вам, то есть событием, значения в момент прохода ещё нет, и обычная стрелка уведёт человека по ветке «пусто» раньше, чем данные доедут. Спасает стрелка с условием по этой переменной: под условием стоит переключатель ожидания («Ждать переменную …»), он включён по умолчанию, и поле «Сколько ждать» — 10 минут. Не дождались — ветка выбирается по тому, что есть («Стрелки: ожидание, время, дожимы»).

«Отправка событий»: всё в аналитику без блоков

Когда аналитику или BI нужны данные по всем воронкам, ставить блок «Вебхук» в каждую не нужно. На вкладке «Отправка событий» → «Добавить адрес» вы указываете адрес, отмечаете, какие события отправлять, и выбираете «Пачкой» или «По одному». События разбиты на группы: «Воронки» (вошёл, прошёл блок, ответил, перешёл по ссылке, блок «ИИ» выбрал выход), «Кнопки ботов», «Переписка», «Клиенты, этапы и теги», «Деньги», «Рассылки».

• Подпись. Каждый запрос подписан заголовком X-Tervio-Signature. Секрет показывается один раз, при создании адреса. Проверяйте подпись на своей стороне, чтобы принимать только события TERVIO.
• «Отправить тестовое событие» — проверка, что адрес отвечает кодом 2xx.
• «Выгрузить историю» — события за прошлый период уходят на адрес с пометкой "history": true.
• «Журнал доставок» — что ушло и что вернул ваш сервер.

Не принимает адрес почти сутки — отправка встаёт на паузу, а CRM присылает уведомление «Отправка событий на паузе». События при этом копятся и после «Возобновить отправку» уходят по порядку. Повторные доставки приходят с тем же id: по нему ваша сторона отсеивает дубли.

Связка целиком: от оплаты до ссылки в ответ

1. Собираете воронку «После оплаты»: «Старт» — «Внешнее событие (вебхук)», ключ payment_ok, «Где вести воронку» — «В личке лида», «Не состояние». Включаете лист.
2. В «Интеграциях» на вкладке «Вебхуки» проверяете, что строка зелёная, и копируете полный URL и «Заголовки одним блоком».
3. На стороне платёжного сервиса (напрямую или через n8n) настраиваете вызов: POST по этому адресу, тело {"event_key":"payment_ok","lead":{"tg_id":…},"vars":{"amount":…},"event_id":…}.
4. Клиент оплатил — CRM находит его по tg_id, запускает воронку и отвечает run_started: true.
5. Первый блок пишет в личку: «Оплата на {amount} ₽ дошла» — сумма подставилась из vars.
6. Дальше блок «Действия»: «Действие TERVIO» → «Сдвинуть этап» на ваш этап оплаты, теперь оплата видна в карточке и в аналитике. Следом в том же блоке «Вебхук»: POST в вашу систему учёта, в «Сохранить ответ» — link -> ssylka.
7. От блока — стрелка с условием по ssylka и ожиданием переменной: пришла ссылка — уходит сообщение с доступом, не пришла — вторая ветка ставит задачу куратору.

Дальше — «ИИ-подсказки ответа, база знаний и блок «ИИ»»: как включить черновики ответов от модели и откуда она берёт факты про вашу школу.