Документация › Для разработчиков › Кастомные вебхуки
Кастомные вебхуки (продвинутый режим)
[продвинутое]Научи бота дёргать твой HTTP-эндпоинт: проверить остаток на складе, создать заказ в своей системе, получить данные из своей БД. Через функцию «Своя интеграция по API» (типwebhook).
⏱ 9 мин · 👤 для разработчика и владельца · 🟢 live
За 30 секунд:
- Функция «Своя интеграция по API» (тип
webhook) даёт боту звонить на твой URL.- Настраиваешь URL, метод, заголовки, тело; в шаблонах можно подставлять данные диалога (выражения).
- Есть повторы при сбоях, таймаут до 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-ответ твоего сервиса в разговоре.
Обратное направление: платформа сама шлёт события на твой URL
Не путай с функцией выше. Функция это когда бот идёт к тебе посреди разговора. А в разделе «Интеграции» → «Вебхуки» настраивается обратное: платформа сама шлёт тебе POST, когда в проекте что-то произошло. Указываешь URL и отмечаешь события чипами.
Доставляются все девять событий (семь из них подключены 2026-08-06):
| Событие | Когда шлётся |
|---|---|
conversation_started | бот ответил в диалоге, которого раньше не было |
message_received | бот ответил в уже существующем диалоге |
lead_created | бот создал заявку |
payment_received | оплата прошла |
tokens_low | баланс проекта на исходе |
trial_expiring | заканчивается бесплатный период WhatsApp |
whatsapp_disconnected | WhatsApp-канал отвалился |
ai_error | бот не смог ответить из-за ошибки ИИ |
schedule_problem | движок записи не разобрал график |
Тело запроса одинаковое: event, project_id, project_name, title, body, data (подробности события) и fired_at.
📌 Про повторы. Событие вроде «мало баланса» может повторяться, пока причина не устранена, поэтому на своей стороне считай доставку идемпотентной: ориентируйся на паруevent+fired_at, а не на «пришло, значит новое».
Доставки видно в «Логах событий»: статус, код ответа, повторы. Подпись платформа на этих запросах не ставит, если нужна аутентификация, положи секрет в query или прими только с известного адреса.
Надёжность: таймаут и повторы
| Параметр | Поведение |
|---|---|
| Таймаут | по умолчанию ~10 сек, настраивается от 1 до 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 хранятся в зашифрованном виде. Одно ограничение: адрес должен быть «внешним» на внутренние/локальные адреса бота направить нельзя, это защита от взлома.
Дальше: → Язык выражений
Связано: Функции · Вебхуки и безопасность · МойСклад: готовый пример · Функция падает
Не получилось? → Функция не вызывается / падает