Документация › Для разработчиков › Кастомные вебхуки
Кастомные вебхуки (продвинутый режим)
[продвинутое]Научи бота дёргать твой HTTP-эндпоинт: проверить остаток на складе, создать заказ в своей системе, получить данные из своей БД. Через функцию «Своя интеграция по API» (типwebhook).
⏱ 9 мин · 👤 для разработчика и владельца · 🟢 live
За 30 секунд:
- Функция «Своя интеграция по API» (тип
webhook) даёт боту звонить на твой URL.- Настраиваешь URL, метод, заголовки, тело; в шаблонах можно подставлять данные диалога (выражения).
- Есть повторы при сбоях, таймаут до 30-60 сек (зависит от режима функции), авторизация к твоему API (Bearer/Basic/API-key): ключи хранятся зашифрованными.
- URL проходит проверку безопасности (SSRF): внутренние адреса заблокированы.
Зачем это нужно
Встроенных функций (запись в Sheets, календарь, CRM) хватает не всем. Если у тебя своя система, склад, ERP, личный бэкенд, кастомный вебхук позволяет боту обратиться к ней прямо в разговоре: клиент спросил «есть ли товар?» → бот дёрнул твой /api/stock → ответил по факту.
Как настроить
Создай функцию типа «Своя интеграция по API» (тип webhook, см. Функции):
- URL, твой эндпоинт (через выражения можно вставить данные:
https://api.shop.kz/order?phone={{phone}}); - метод: GET или POST;
- заголовки: свои, включая авторизацию;
- тело (для POST): шаблон с подстановкой полей диалога;
- описание, когда боту это звать (как у любой функции).
Бот сам решит, когда вызвать, передаст параметры и использует JSON-ответ твоего сервиса в разговоре.
Надёжность: таймаут и повторы
| Параметр | Поведение |
|---|---|
| Таймаут | по умолчанию ~10 сек, настраивается: до 30 сек (стандартный режим) / до 60 сек (расширенный режим функции) |
| Повторы | настраиваемые: число попыток + задержка (линейная/экспоненциальная) |
| Авто-повтор | временные коды 408, 429, 502, 503, 504, 522, 524 повторяются всегда; 429 уважает Retry-After |
Если твой сервис «прилёг», бот не зависнет, отработает таймаут и повторы, а клиенту скажет, что не получилось (см. Функция падает).
Авторизация к твоему API
Бот может авторизоваться на твоём эндпоинте: Bearer-токен, Basic, API-ключ в заголовке или кастомный заголовок. Эти секреты хранятся зашифрованными. Заголовки очищаются от спецсимволов (защита от инъекций), а служебные заголовки слать нельзя.
⚠️ URL проверяется на безопасность. Нельзя направить бота на внутренний адрес (127.0.0.1,10.x,192.168.xи т.п.): это блокируется (SSRF-защита). Эндпоинт должен быть публичным и желательно по HTTPS.
Простыми словами
Это для тех, у кого есть своя программа или сайт с API. Обычный бот умеет писать в Google-таблицу или CRM, но если тебе нужно дёрнуть именно свою систему, например, проверить остаток на складе или создать заказ: ты настраиваешь «Свою интеграцию по API». Говоришь боту: вот адрес, вот как авторизоваться, вот что отправить, и он по ходу разговора обращается к твоему сервису и отвечает клиенту по реальным данным.
Сделано надёжно, если твой сервер тормозит, бот не зависнет, подождёт сколько-то секунд, попробует ещё раз, а не получилось, честно скажет клиенту. Пароли к твоему API хранятся в зашифрованном виде. Одно ограничение: адрес должен быть «внешним» на внутренние/локальные адреса бота направить нельзя, это защита от взлома.
Дальше: → Язык выражений
Связано: Функции · Вебхуки и безопасность · МойСклад: готовый пример · Функция падает
Не получилось? → Функция не вызывается / падает