Входящий API-вебхук для запуска воронки Telegram нужен, когда событие появляется не в боте. Человек оплатил на сайте, менеджер перевел сделку в CRM, LMS открыла доступ, backend посчитал скоринг, платежка прислала статус. В этот момент внешняя система должна не просто записать факт, а запустить нужную цепочку сообщений для конкретного контакта.
Короткий вывод: рабочая схема состоит из трех частей. В Strelo создается API-ссылка, во внешней системе отправляется POST с полем event и идентификатором контакта, в конструкторе публикуется триггер "Внешнее событие API" с тем же ключом события. Если контакт найден, воронка стартует фоном и получает весь payload как переменные.
Для каких задач эта схема нужна
Онлайн-школа с LMS
Платформа обучения или сайт отправляет событие оплаты, регистрации или открытия урока, а бот выдает доступ и запускает дожим.
Telegram-магазин
Склад, CRM или платежка меняет статус заказа, после чего Telegram-воронка пишет клиенту о платеже, доставке или повторной покупке.
Отдел продаж
Менеджер переводит сделку в CRM на новый этап, а бот отправляет персональное сообщение без ручного копирования.
Свой backend
Сервис считает скоринг, проверяет условия и вызывает Strelo только тогда, когда действительно нужно запустить Telegram-цепочку.
Что должно совпасть, чтобы цепочка стартовала
API-ссылка
Вебхук создается в настройках Strelo и принимает POST на /api/hooks/<token>.
Event key
Значение поля event в payload должно совпадать с ключом события в триггере воронки.
Контакт
В запросе нужен contact_id, telegram_id, email, username, external_id, phone или другой идентификатор.
Secret
Для боевого запуска используйте дополнительный secret в заголовке, а не только публичный URL.
Когда нужен входящий API-вебхук
Входящий API-вебхук нужен не для каждого сообщения пользователя. Он нужен для событий, которые происходят за пределами Telegram, но должны поменять коммуникацию внутри Telegram. Например, человек оставил заявку на сайте, но дальше вы хотите отправить ему серию сообщений в боте. Или заказ оплатили в платежной форме, а бот должен выдать доступ и поставить тег.
Если событие родилось в самом сценарии, чаще хватает обычной ноды "Внешний запрос API" или встроенных действий Strelo. Если событие родилось в CRM, платежке, LMS, форме сайта, рекламном кабинете или своем backend, нужен обратный маршрут в сторону Strelo.
Когда нужен входящий webhook, а когда другой инструмент
Выбирайте маршрут по месту рождения события. Если событие произошло вне Telegram, нужен вход в Strelo. Если событие произошло внутри сценария, чаще нужен исходящий запрос.
| Критерий | Событие | Лучший маршрут | Пример |
|---|---|---|---|
| Оплата на сайте | Возникла вне бота | Входящий API-вебхук | order_paid запускает выдачу доступа |
| Лид оставил телефон в боте | Возникло внутри сценария | Исходящий HTTP-запрос в CRM | Сценарий отправляет лид в сделку |
| Менеджер сменил этап сделки | Возникло в CRM | Входящий API-вебхук | proposal_sent запускает follow-up |
| Заказ создается в Strelo | Возникло в воронке | Нода продаж или оплата | Заказ, платеж, тег покупки |
Главное не путать эту схему со служебным webhook Telegram Bot API. Служебный webhook получает входящие сообщения от Telegram. Пользовательская API-ссылка Strelo принимает бизнес-событие от вашей системы и запускает опубликованную воронку для контакта.
Из каких деталей состоит схема
Схема выглядит просто, но ломается, если хотя бы одна деталь не согласована. Нужны API-ссылка, event key, идентификатор контакта, payload, защита и опубликованная воронка. Без event Strelo не поймет, какая ветка нужна. Без идентификатора контакта воронка не знает, кому писать. Без секрета публичный URL можно дернуть вручную.
Пять элементов входящего API-вебхука
Если один элемент пропущен, событие может прийти, но воронка не стартует или стартует не для того контакта.
| Критерий | Элемент | Зачем нужен | Риск ошибки |
|---|---|---|---|
| URL | /api/hooks/<token> | Принимает POST от внешней системы | Выключенный или старый token даст 404 |
| event | order_paid | Выбирает нужный external_event триггер | Пустой event вернет 400 |
| contact id | telegram_id, email, external_id | Привязывает событие к человеку | Без совпадения запуск будет пропущен или создаст новый контакт |
| secret | X-Strelo-Secret или Bearer | Защищает боевой URL | Неверный secret вернет 401 |
| payload | amount, product, access_url | Становится переменными воронки | Слишком большой JSON трудно поддерживать |
В Strelo API-ссылка имеет вид /api/hooks/<token>. Token в URL уже ограничивает доступ к конкретному вебхуку. Дополнительно можно включить secret, тогда внешняя система передает его в заголовке X-Strelo-Secret или как Bearer token. Это особенно важно для событий оплаты, доступа, статуса заказа и любых сценариев, где фальшивый вызов может привести к выдаче материала или неверному статусу.
Что отправлять в POST-запросе
Минимальный payload содержит event и один идентификатор контакта. Идентификатором может быть contact_id, telegram_id, email, username, external_id, phone или другое поле, по которому контакт уже есть в Strelo. Остальные поля payload попадут в переменные воронки и смогут использоваться в сообщениях, условиях и действиях.
Минимальный и расширенный набор полей
Минимум
event плюс один идентификатор контакта: contact_id, telegram_id, email, username, external_id или phone.
Полезный контекст
order_id, product_id, amount, tariff, manager_name, booking_time, access_url, source и stable_id.
Не отправлять
Токены, внутренние промпты, лишние персональные данные, полный объект CRM и поля, которые воронка не использует.
Формат
JSON или form-urlencoded. Для поддержки и тестов удобнее JSON с плоскими ключами без вложенных структур.
Хорошая практика - не называть event слишком общо. Event update почти бесполезен: он не говорит, что случилось. Лучше использовать registration_created, lead_qualified, order_paid, lesson_opened, manager_assigned, trial_expired. Название должно объяснять, какую ветку запускать и почему именно сейчас.
Как назвать event, чтобы через месяц все было понятно
По факту, не по системе
order_paid понятнее, чем crm_update. В названии должно быть действие, а не источник.
Разделяйте этапы
registration_created, lead_qualified и trial_expired должны запускать разные ветки.
Не используйте update
Один event на все превращает воронку в набор условий, где никто не уверен, что произошло.
Ведите словарь
Таблица event, источник, обязательные поля, воронка и владелец экономит часы отладки.
Для онлайн-школы payload может содержать course_id, tariff, order_id, amount, currency и access_url. Для консультаций - manager_name, booking_time, lead_score и topic. Для магазина - product_id, delivery_city, order_status и payment_id. Не нужно передавать весь объект CRM, если воронке нужны только 6-10 рабочих полей.
Как Strelo находит контакт
После получения POST Strelo ищет контакт внутри конкретного workspace. Сначала проверяется прямой contact_id, потом telegram_id, email, username, external_id и дополнительные параметры. Поиск не выходит за пределы workspace, поэтому совпадение email или external_id в чужом аккаунте не запустит чужую воронку.
Как входящее событие превращается в запуск воронки
Внешняя система отправляет POST
В URL передан token вебхука, в теле есть event и идентификатор контакта.
Strelo проверяет доступ
Если вебхук выключен, вернется 404. Если задан secret и он неверный, вернется 401.
Контакт ищется внутри workspace
Проверяются contact_id, telegram_id, email, username, external_id и дополнительные параметры.
Запускается external_event
Опубликованная воронка с совпавшим event key стартует фоном и получает payload как переменные.
Если контакт не найден, поведение зависит от настройки вебхука. По умолчанию запрос можно пропустить без запуска. Если включена опция создания контакта, Strelo создаст нового API-контакта, сохранит переданные поля в metadata и запустит сценарий. Это удобно для заявок с сайта, но опасно для мусорного трафика, если нет проверки secret и фильтра событий.
Какой идентификатор передавать
Чем стабильнее идентификатор, тем меньше дублей и ручных правок в CRM.
| Критерий | Идентификатор | Когда использовать | Ограничение |
|---|---|---|---|
| contact_id | Внутренний ID Strelo | Лучший вариант, если контакт уже синхронизирован | Нужно хранить его во внешней системе |
| telegram_id | ID пользователя Telegram | Сильный вариант для бот-сценариев | Должен быть собран заранее |
| email или phone | Контактные данные | Удобно для сайта, CRM и форм | Могут быть дублями или разным форматом |
| username | @username | Подходит как запасной вариант | Меняется и может отсутствовать |
| external_id | ID из CRM или LMS | Удобен при глубокой интеграции | Нужно один раз правильно записать в metadata |
Не рассчитывайте только на username. Его можно сменить, он может отсутствовать, а в CRM он часто хранится без @ или в произвольном виде. Для Telegram-сценариев сильнее telegram_id, для внешней CRM - contact_id или external_id, для сайта - email и phone. Чем стабильнее идентификатор, тем меньше дублей и ручной чистки.
Как настроить триггер в воронке
В конструкторе Strelo создайте флоу с триггером "Внешнее событие API". В поле "Ключ события" укажите то же значение, которое внешняя система отправляет в payload.event. Если CRM отправляет event = order_paid, триггер тоже должен ждать order_paid.
Порядок запуска в Strelo
Создайте API-вебхук
В настройках откройте API-вебхуки, задайте имя, включите secret и решите, создавать ли контакт, если он не найден.
Передайте URL внешней системе
Скопируйте /api/hooks/<token>, добавьте заголовок с secret и подготовьте JSON payload.
Создайте триггер
В воронке выберите Внешнее событие API и укажите ключ события, например order_paid.
Проверьте POST
Отправьте событие на тестовом контакте, проверьте запуск, переменные и сообщение в Telegram.
У такого триггера фоновая логика. Он запускается из API-события, не как ответ на входящее сообщение. Это полезно, потому что текущий диалог пользователя не обязан прерываться: человек может общаться с менеджером, а внешнее событие параллельно запустит выдачу доступа, напоминание, тег или ветку дожима.
Если у контакта нет канала, с которого можно отправить сообщение, сценарий не сможет написать в Telegram. Поэтому перед запуском боевой схемы проверьте: контакт уже писал в бота или привязан к Telegram-каналу, у канала есть активный bot token, бот не заблокирован пользователем.
Какие сценарии стоит запускать входящим webhook
Самый понятный сценарий - оплата. Платежка или CRM сообщает order_paid, Strelo находит контакт, ставит тег покупки, отправляет инструкцию и запускает ветку доступа. Второй сценарий - регистрация на вебинар. Сайт отправляет registration_created, бот присылает материалы, дату, кнопку добавить напоминание и дожим до оплаты.
Какие event обычно запускают Telegram-цепочку
order_paid
Оплата подтверждена, бот выдает доступ, ставит тег покупки и отправляет инструкцию.
booking_created
Запись на консультацию создана, бот отправляет дату, подготовку и напоминания.
lead_qualified
Лид прошел квалификацию, бот передает менеджеру контекст и запускает теплый follow-up.
lesson_opened
LMS открыла доступ к модулю, бот присылает ссылку и подсказки по старту.
trial_expired
Тестовый период закончился, бот отправляет оффер продления и отвечает на частые вопросы.
manager_assigned
CRM назначила менеджера, бот сообщает имя, время связи и следующий шаг.
Третий сценарий - смена статуса сделки. Менеджер в CRM поставил stage = proposal_sent, и бот отправляет клиенту короткое сообщение с резюме предложения. Четвертый - скоринг. Backend посчитал, что лид горячий, и запускает персональную ветку с приглашением на консультацию.
Входящий webhook не должен заменять все бизнес-процессы. Его задача - соединить момент события с правильным Telegram-действием. Если действие не должно происходить сразу или зависит от сложной модерации, лучше принять событие в backend, проверить условия, а уже потом дергать Strelo.
Безопасность: публичный URL не должен быть открытой дверью
Вебхук - публичный URL. Если он запускает воронку, выдает доступ или меняет статус контакта, его нельзя оставлять без дополнительной защиты. Минимум: длинный token в URL, secret в заголовке, понятный список допустимых event и логирование ошибок. Для чувствительных событий добавьте стабильный external_id или order_id, чтобы повторный запрос не создавал второй запуск.
Что обязательно сделать перед боевым трафиком
- Secret передается заголовком, а не в тексте сообщения или query-параметре.
- Есть список допустимых event и владелец каждого события.
- Повторная доставка одного order_id не создает новый сценарий без необходимости.
- Ошибки 400, 401, 404 и контакт не найден проверены до запуска.
- URL лежит в открытой документации внешнего подрядчика.
- Любой event принимается без фильтра и может запустить цепочку.
- Событие оплаты приходит без order_id или payment_id.
- Неверный secret внешняя система считает успешной доставкой.
Не передавайте secret в названии события, query-параметре, комментарии к сделке или теле сообщения пользователю. Заголовок проще спрятать в настройках CRM или backend. Если secret засветился в чате или тикете, ротируйте его, а не надейтесь, что URL "никто не найдет".
Какие ответы должен понимать внешний сервис
Контакт найден или корректно обработан пропуск без запуска.
Payload собран неверно, событие нельзя запускать.
Нужно остановить доставку и исправить настройки авторизации.
Token старый, вебхук удален или отключен.
Для тестов можно начать без secret, но только на черновом вебхуке и тестовом контакте. В боевом запуске secret должен быть включен, а внешний сервис должен корректно обрабатывать 401 и 404, а не молча считать событие доставленным.
Идемпотентность и дубли
Любая внешняя система может повторить webhook. Это нормальное поведение: сеть оборвалась, endpoint ответил слишком долго, сервис не получил подтверждение и отправил событие еще раз. Проблема начинается, когда повтор создает второй заказ, второй тег покупки и вторую серию сообщений.
Как не запустить одну и ту же ветку пять раз
Stable ID
Передавайте order_id, payment_id, lead_id или event_id для повторяемого события.
Повторный POST
Тестируйте retry вручную: один и тот же payload не должен приводить к хаосу.
Timestamp не ключ
Время полезно для аудита, но оно не защищает от дублей, потому что меняется при повторе.
В payload лучше передавать stable_id: order_id, payment_id, lead_id, booking_id или event_id. Воронка может использовать его как переменную, а внешняя CRM - как ключ для обновления. Timestamp не подходит как основной ключ, потому что у каждого повтора будет новое время.
Если событие действительно должно запускаться несколько раз, например lesson_reminder для разных уроков, включите в stable_id номер урока или дату. Тогда повторы одного урока будут отличаться от новых событий, а случайные retry не создадут хаос.
Переменные payload внутри воронки
Все поля входящего payload становятся строковыми переменными сценария. Это позволяет сразу вставить в сообщение сумму, название продукта, дату консультации, ссылку на доступ или имя менеджера. Например, после order_paid бот может написать: "Оплата по тарифу Pro получена, ссылка на доступ ниже" и подставить access_url.
Какие поля стоит отдавать в воронку
Payload должен помогать сценарию написать точное сообщение, а не превращаться в копию всей CRM.
| Критерий | Поле | Где использовать | Комментарий |
|---|---|---|---|
| amount | Сумма оплаты | Сообщение после платежа | Передавайте вместе с currency |
| tariff | Название тарифа | Выдача доступа или сегмент | Не смешивайте с product_id |
| manager_name | Имя менеджера | Персональное уведомление | Проверьте, что поле не пустое |
| access_url | Ссылка на материал | Выдача доступа | Не передавайте секретные токены без срока жизни |
| source | Источник события | Аналитика и сегментация | Используйте фиксированные значения |
Но переменные не должны превращаться в свалку. Если в payload прилетает огромный JSON с вложенными объектами, редактору воронки будет трудно понять, какие поля можно использовать. Лучше сделать тонкий контракт: 8-12 стабильных ключей, понятные имена, строковые значения, отдельный stable_id.
Для команд полезно вести маленький словарь событий. В нем перечислены event, когда он отправляется, какие поля обязательны, что делает воронка и кто отвечает за внешний источник. Это дешевле, чем через месяц разбираться, почему order_success и order_paid запускают разные ветки.
Как протестировать перед боевым запуском
Не тестируйте только счастливый путь. Проверьте минимум шесть случаев: правильный secret, неправильный secret, пустой event, неизвестный event, контакт найден, контакт не найден. Потом повторите один и тот же webhook дважды и посмотрите, не ушли ли два одинаковых сообщения.
Минимальный план проверки перед запуском
Успешный вызов
Отправьте POST с правильным event, secret и контактом, проверьте запуск ветки и переменные.
Неверный secret
Внешняя система должна увидеть 401 и не считать событие доставленным.
Контакт не найден
Проверьте оба режима: пропуск без запуска и создание нового контакта, если эта опция включена.
Повтор события
Отправьте тот же payload дважды и проверьте сообщения, теги и статусы.
Несовпавший event
Отправьте неизвестный event и убедитесь, что не запускается случайная ветка.
Сценарий теста должен идти от реального источника. Если в бою событие отправит CRM, тестируйте CRM, а не curl с ноутбука. Если в бою событие отправит сайт, нажмите тестовую форму на сайте. Curl нужен для изоляции проблемы, но он не доказывает, что реальная интеграция собрана правильно.
Какие сигналы смотреть в первые сутки
Сколько POST дошло до Strelo и какие event встретились.
Высокая доля говорит, что выбран слабый идентификатор контакта.
Повторы нормальны, но не должны создавать лишние действия.
Число принятых событий должно совпадать с ожидаемыми стартами ветки.
После первого дня работы посмотрите логи и контакты. Сколько событий пришло, сколько контактов не нашлось, сколько запусков было повторными, какие event не совпали с триггером, сколько сообщений не отправилось из-за отсутствующего Telegram-канала. Эти цифры быстро покажут, где контракт нужно уточнить.
Чем входящий API-вебхук отличается от интеграции продаж
В Strelo есть разные входы для событий. Пользовательский API-вебхук подходит для произвольных событий: регистрация, статус, скоринг, запись, ручное действие из CRM, сигнал с сайта. Интеграции продаж и commerce webhook лучше подходят, когда нужно учитывать заказ, оплату, продукт, провайдера и аналитику выручки.
API-вебхук, commerce webhook или встроенная оплата
Не каждый входящий вызов нужно превращать в external_event. Для денег и заказов иногда лучше специализированный маршрут.
| Критерий | Задача | Что выбрать | Почему |
|---|---|---|---|
| Запустить коммуникацию | Смена статуса, регистрация, скоринг | API-вебхук и external_event | Нужна ветка сообщений, а не учет выручки |
| Учесть оплату | Оплата, заказ, возврат | Платежная нода или commerce webhook | Нужны статусы, продукт и выручка |
| Передать лид наружу | Контакт собран в боте | Исходящий HTTP-запрос | Событие родилось в Strelo, не снаружи |
| Сложная бизнес-логика | Много проверок до запуска | Свой backend плюс API-вебхук | Backend фильтрует, Strelo коммуницирует |
Если событие меняет коммуникацию, используйте API-вебхук и external_event. Если событие является заказом или оплатой, проверьте, не лучше ли использовать ноды продаж, встроенную оплату или commerce integration. В реальном проекте эти маршруты часто работают вместе: платежка фиксирует покупку, а external_event запускает персональную ветку выдачи доступа.
Что делает Strelo удобным для такой схемы
В классической связке разработчик поднимает endpoint, пишет обработчик, ищет contact_id, проверяет секрет, создает задачу, отправляет сообщение через Telegram Bot API и следит за дублями. В Strelo большая часть этого уже собрана как продуктовый контур: API-ссылка, контактная база, Telegram-канал, визуальная воронка, теги, условия, сообщения, оплаты и аналитика.
Когда Strelo закрывает задачу лучше самописного слоя
- Нужно быстро запускать Telegram-ветки по событиям CRM, сайта или LMS.
- Команда хочет менять сообщения, условия и теги без разработчика.
- Контакты, история, оплаты, AI и аналитика должны быть рядом с воронкой.
- События типовые: регистрация, оплата, статус, запись, доступ, дожим.
- Перед запуском события нужно пройти много внутренних проверок.
- Внешняя система требует сложную подпись, трансформацию или очереди.
- Нужны жесткие SLA, повторная доставка и централизованный audit log.
- Telegram - только один из многих каналов корпоративной интеграции.
Strelo не отменяет внешний backend, если у вас сложная логика. Но он убирает лишний код там, где задача типовая: событие пришло, контакт найден, ветка стартовала, менеджер видит историю, бот отправил нужное сообщение. Для онлайн-школы, Telegram-магазина или экспертного продукта это часто быстрее, чем делать свою мини-платформу вокруг Bot API.
Чеклист запуска
Перед запуском зафиксируйте event contract в одном месте. Укажите, кто отправляет событие, какой URL использует, какой secret, какие поля обязательны, какой контактный идентификатор главный, какая воронка запускается и что считать успешной доставкой.
Что должно быть готово перед первым боевым POST
Event contract
Список event, обязательных полей, источников и ответственных за каждый внешний сервис.
Secret и token
Боевой URL не лежит публично, secret передается заголовком и может быть ротирован.
Главный ID
Понятно, какой идентификатор контакта основной и какой используется как запасной.
Опубликованная воронка
Триггер external_event активен, event key совпадает, ветка не является черновиком.
Негативные тесты
Проверены неверный secret, пустой event, неизвестный event, контакт не найден и повтор payload.
Первые метрики
После запуска есть контроль пришедших событий, пропусков контакта, повторов и фактических стартов.
После этого проведите боевой тест на одном реальном контакте: создать событие во внешней системе, дождаться запуска воронки, проверить переменные, убедиться, что контакт и CRM-запись совпали. Только после этого подключайте массовый поток заявок, оплат или регистраций.
Итог
Входящий API-вебхук - это не "просто ссылка". Это контракт между внешней системой и Telegram-воронкой. Он должен отвечать на пять вопросов: какое событие произошло, кого оно касается, можно ли доверять запросу, какие данные нужны сценарию и что делать при дубле.
Если эти вопросы закрыты, API-вебхук превращает Strelo в понятный Telegram-слой вокруг CRM, сайта, платежки или backend. Внешняя система продолжает быть источником события, а Strelo берет на себя коммуникацию: найти контакт, запустить ветку, отправить сообщение, поставить тег, передать менеджеру и показать результат в воронке.
Запускайте цепочки в Strelo по событиям из CRM, сайта и платежек
Создайте API-вебхук, настройте external_event, передавайте payload и запускайте персональные Telegram-сценарии без самописной прослойки для каждого события.
Открыть StreloЧастые вопросы
Что такое входящий API-вебхук для Telegram-воронки?
Это публичная API-ссылка, на которую внешняя система отправляет событие. Strelo находит контакт и запускает опубликованную Telegram-воронку с триггером external_event.
Нужно ли писать backend для запуска воронки по webhook?
Не всегда. Если внешняя система умеет отправить POST с event, идентификатором контакта и secret, можно вызвать API-вебхук Strelo напрямую. Backend нужен для сложной проверки, очередей, трансформации данных или нестандартной подписи.
Какой event key лучше использовать?
Используйте названия по факту события: order_paid, registration_created, lead_qualified, lesson_opened, trial_expired. Не используйте общий update, если разные события должны запускать разные ветки.
Что будет, если контакт не найден?
Если создание контакта выключено, Strelo вернет ok и skipped contact_not_resolved. Если создание включено, будет создан API-контакт, и воронка сможет стартовать для него.
Можно ли запускать воронку по email?
Да, если email есть в карточке контакта внутри того же workspace. Для Telegram-first сценариев надежнее хранить telegram_id или contact_id, а email использовать как запасной идентификатор.
Почему webhook вернул 401?
У вебхука включен secret, но внешний сервис не передал его или передал неверное значение. Проверьте заголовок X-Strelo-Secret или Authorization Bearer.
Можно ли передать дополнительные поля из CRM в сообщение бота?
Да. Поля payload становятся переменными воронки. Их можно подставлять в сообщения, условия и действия, если имена полей стабильны и понятны редактору сценария.
Чем API-вебхук отличается от интеграции оплаты?
API-вебхук запускает коммуникацию по произвольному событию. Интеграция оплаты или commerce webhook лучше подходит для учета заказа, статуса платежа, продукта и выручки.