Интеграция
Интеграция для систем, под которые никто не написал коннектор
Интеграция через универсальные вебхуки соединяет Telegram-бота с любой системой, которая умеет отправить или принять HTTP-запрос. Так подключаются самописные ERP, внутренние инструменты и малоизвестные SaaS. Любой вебхук доставляется как минимум один раз, а значит каждый обработчик обязан быть идемпотентным — в этом вся дисциплина.
Универсальные вебхуки — интеграция: доступ, лимиты и доступность
- Модель авторизации
- Подпись HMAC
- Семантика доставки
- Как минимум один раз — практически в любой реализации
- Доступность в Заливе
- Любая система, говорящая по HTTP, включая локальные логистические системы стран Залива
- Поток данных
- 5 узлов, через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
Почти у каждого бизнеса есть хотя бы одна система, под которую никто не писал коннектор. ERP, которую подрядчик допиливал в 2016 году, внутренний инструмент диспетчеризации, платформа бронирования, популярная ровно в одной стране. Такие системы, как правило, умеют отправить HTTP-запрос, когда что-то произошло, и принять его, когда что-то надо сделать. Этого достаточно.
Работа с универсальными вебхуками разваливается потому, что её считают проще настоящей интеграции. Документированный API рассказывает про rate limit, поведение при повторах и гарантии доставки. Вебхук из самописной системы не рассказывает ничего, поэтому предположения приходится делать явно и консервативно: считайте, что доставка произойдёт дважды, что события придут не по порядку и что иногда какое-то не придёт вовсе.
Из этих трёх предположений вырастает вся архитектура. Ключи идемпотентности — чтобы дубликат ничего не менял. Обработка по состоянию, а не по приращению — чтобы порядок не имел значения. Сверка — чтобы недоставленное событие было замечено, а не ожидалось вечно. Интеграция на вебхуках, построенная на таких допущениях, работает почти с чем угодно; построенная на вере в доставку ровно один раз — ровно до того дня, когда отправитель повторит запрос.
Как на самом деле движутся данные
Входящие вебхуки проверяются подписью HMAC по сырому телу запроса на общем секрете, с проверкой свежести отметки времени, чтобы перехваченный запрос нельзя было воспроизвести позже. Там, где отправляющая система не умеет подписывать, запасной вариант — секрет в заголовке, а сам путь эндпоинта считается чувствительным. Это слабее, и мы так и говорим, а не выдаём за равноценное решение.
Модель доступа: Запросы с подписью HMAC
Их лимиты и что они означают для вас
Доставка вебхука практически в любой реализации происходит как минимум один раз.
Обработчики идемпотентны по ключу из полезной нагрузки. Расчёт на доставку ровно один раз работает до первого повтора, а тот обычно приходит прямо во время того инцидента, из-за которого отправитель и начал повторять.
Порядок доставки не гарантирован, особенно после повтора.
Обработчики рассуждают о состоянии, описанном в событии, а не применяют приращение. Тогда пара событий, пришедшая не по порядку, даёт правильное итоговое состояние, а не перевёрнутое.
Большинство отправителей отваливается по тайм-ауту за несколько секунд и считает медленный ответ отказом.
Эндпоинт быстро подтверждает приём, а работу делает после. Работа внутри запроса порождает повторы, повторы порождают дубликаты, а дубликаты — ровно ту проблему, ради которой идемпотентность и существует.
Самописные системы часто вообще не умеют подписывать запросы.
Запасной вариант — общий секрет в заголовке плюс неугадываемый путь, и он слабее. Сказать это прямо честнее, чем выдавать за равную по стойкости защиту.
Как это ломается и что происходит потом
Одно и то же событие доставлено дважды, и клиент получил два уведомления.
Нужна дедупликация по ключу идемпотентности. Это самый частый дефект интеграций на вебхуках и самый заметный для клиента.
Обновление статуса пришло раньше события, создавшего запись.
Обработчик создаёт или обновляет запись из состояния в полезной нагрузке, а не рассчитывает, что запись уже есть. Настаивать на порядке — значит выбрасывать события, пришедшие первыми.
Отправитель перестал доставлять события, и этого никто не заметил.
Проверка на залежавшиеся данные оповещает, когда ожидаемый поток молчит дольше обычного интервала. Молчание — самый трудный для обнаружения сбой и самый дорогой, если обнаружить его поздно.
Эндпоинт отвечает медленно, и отправитель раз за разом повторяет одно и то же событие.
Сначала подтверждение, потом обработка. Медленный обработчик превращает одно событие в шквал дубликатов, причём отправитель всё это время ведёт себя правильно.
Доступность в ОАЭ и остальных странах Залива
Любая система, говорящая по HTTP
В этом и смысл интеграции. Там, где есть документированный коннектор, он обычно лучше; там, где его нет, ответ именно такой.
Системы на собственных серверах
Частый случай в логистике и на производстве в странах Залива. Исходящие вебхуки обычно работают; входящим нужно, чтобы система была достижима, а это разговор про сеть, а не про код.
Системы без обратного вызова
Запасной вариант — опрос с тем интервалом, который система выдерживает. Медленнее и шумнее, и иногда это единственный доступный путь.
Регулируемые потоки данных
Универсальный вебхук несёт то, что в него положил отправитель. Если это персональные или финансовые данные, транспорт и сроки хранения требуют того же внимания, что и в любой другой интеграции.
Когда эту интеграцию делать не нужно
- Под эту систему уже есть документированный коннектор. Он возьмёт на себя постраничную выдачу, обновление токенов и rate limit, которые иначе придётся писать заново.
- Отправляющая система не умеет подписывать запросы, а данные чувствительные. Секрет в заголовке слабее, и делать вид, что это одно и то же, — неверный размен для персональных или финансовых данных.
- Вам нужна гарантированная обработка ровно один раз от начала до конца. Вебхуки её не дают; идемпотентность делает безопасной доставку «как минимум один раз», а это другая гарантия.
- Система не умеет ни отправлять, ни принимать HTTP. Тогда это не та интеграция, и честный ответ — опрос базы данных или каталога, куда складываются файлы.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Проверка подписи, быстрое подтверждение приёма и отложенная обработка. |
| Cloudflare D1 | current | Ключи идемпотентности, журнал событий и отслеживание замолчавших потоков. |
| Zod | 4.4 | Валидация полезной нагрузки, форму которой вы не контролируете и на которую нельзя полагаться. |
| grammY | 1.45 | Исходящее уведомление в Telegram. |
Вопросы, которые возникают при оценке
Почему каждый обработчик обязан быть идемпотентным?
Потому что доставка вебхука практически в любой реализации происходит как минимум один раз. Отправитель, не получивший быстрого подтверждения, повторяет запрос — и правильно делает. Идемпотентность и есть то, что делает этот повтор безопасным, а не дублирующим.
Что если события приходят не по порядку?
Обработчики рассуждают о состоянии, описанном в полезной нагрузке, а не применяют приращение к тому, что у них уже есть. Тогда пара событий, пришедшая в обратном порядке, сходится к правильному итоговому состоянию, а не переворачивает его.
Насколько быстро должен отвечать эндпоинт?
Быстрее, чем отправитель отвалится по тайм-ауту, а это обычно несколько секунд. Сначала подтвердите приём, работу сделайте после: медленный обработчик превращает одно событие в шквал повторов, хотя отправитель всё это время ведёт себя правильно.
Что делать, если отправляющая система не умеет подписывать запросы?
Запасной вариант — общий секрет в заголовке плюс неугадываемый путь. Это слабее подписи HMAC, и мы прямо об этом говорим, а не выдаём за равноценную защиту, потому что разница существенна, если данные чувствительные.
Как понять, что поток событий прекратился?
По проверке на залежавшиеся данные: она оповещает, когда ожидаемый поток молчит дольше обычного интервала. Молчание заметить труднее всего, потому что ничего не падает с ошибкой и все панели выглядят здоровыми.
Это дешевле полноценного коннектора?
Обычно да, и только потому, что поверхность меньше. Дисциплина остаётся ровно той же, и попытка её пропустить даёт интеграцию, которая проходит тесты и дублирует клиентские уведомления в продакшене.
Что почитать дальше
Там, где связку можно собрать вообще без кода, стоит рассмотреть интеграцию с Zapier.
Чаще всего входящий вебхук потребляет бот рассылки уведомлений.
Отправления, приходящие из уже работающей системы, используют ровно этот приём в сборке бота отслеживания доставки.
Если другая система на деле является таблицей, путь проще — интеграция с Google Sheets.