# Веб-хуки Веб-хуки — это простой способ, с помощью которого одно приложение может уведомлять другое о каком-то событии в реальном времени. ## Описание работы {% hint style="warning" %} Ваш вебхук будет получать запросы **с разных IP-адресов.** {% endhint %} Предположим, вы создаете бота, который автоматически обрабатывает заказы пользователей, скажем, на сайте интернет-магазина. В этот бот встроена возможность использовать веб-хуки для того, чтобы другие системы узнавали о ключевых событиях. Вот как это работает: 1. **Создание веб-хука**: Вы создаете веб-хук для какого-то важного события, например, завершения обработки заказа. В процессе создания вы указываете URL-адрес, на который нужно отправить уведомление, когда произойдет определенное событие. 2. **Происходит событие**: В диалоге с Савви пользователь делает заказ, и Савви успешно его обрабатывает. После завершения всех вычислений и операций, Савви понимает, что пришло время уведомить другие системы об этом. 3. **Отправка веб-хука**: Сразу после успешного завершения обработки заказа, Савви отправляет HTTP-запрос на указанный URL, содержащий информацию о заказе — его статус, номер, детали и т.д. Этот запрос как раз и называется веб-хуком. 4. **Обработка на стороне получателя**: Другая система — например, сервис доставки или CRM — получает этот запрос (веб-хук) и использует его для выполнения дальнейших действий. Допустим, CRM получает уведомление и обновляет данные клиента о его новом заказе, или сервис доставки начинает подготовку к отправке посылки. Таким образом, использование веб-хуков в Савви позволяет легко и автоматически интегрировать его с другими приложениями и сервисами, устраняя необходимость в постоянных проверках статуса и давая возможность сразу же реагировать на произошедшие события. Это делает взаимодействие между системами более быстрым, точным и удобным. Теперь пройдемся подробнее по техническим особенностям каждого из этапов. ## Создание веб-хука {% stepper %} {% step %} ### Перейдите во вкладку Действия и нажмите на кнопку "Добавить"
{% endstep %} {% step %} ### Выберите тип шага Вебхук Тип шага "Вебхук" находится в разделе API-вызовы. О других типах шагов, таких как "Чтение ссылок", "Вызов бота", "Переключение бота" и прочих мы расскажем в следующих разделах, в данном случае нас интересует веб-хук.
{% endstep %} {% step %} ### Настройте вебхук При выборе откроется форма шага 1:
**Название действия** - просто название для отображения в списке. **Название шага** - название самого шага.
**Переменные действий** - это переменные, которые необходимо заполнять ботом, и которые далее можно будет выбирать при добавлении шагов / вызове конкретных запросов. > Например, вы используете вызов по API для получения данных по заказу используя телефон клиента и дату рождения. Вы можете задать тут сразу эти переменные и бот поймет, что их нужно собирать у клиента перед вызовом API. При добавлении шагов эти переменные будут заполняться конкретными значениями и их можно подставлять в нужные места.
**Константы действия** - это конкретные постоянные значения, которые можно задать фиксированно и которые можно вызывать во всех последующих шагах. > Например, вам понадобилось обратиться по API к какому-то сервису. При этом, при вызове этого сервиса используется какое-то конкретный ваш токен, который необходимо передавать на нескольких шагах. Используя константы, можно задать этот токен один раз и потом выбирать его, без необходимости прописывать его каждый раз на каждом шаге отдельно. > {% endstep %} {% step %} ### Настройка раздела "Условия срабатывания"
**Название функции** - это название функции, которое будет видеть бот. Данное название указывается на английском без пробелов. Название должно отображать общий смысл действия. {% hint style="success" %} После заполнения названия действия можно нажать на кнопку 🔃 справа от поля. Тогда название сгенерируется **автоматически.** {% endhint %} **Описание функции** - более подробное описание смысла действия. По данному описанию Савви будет понимать, когда ее нужно вызывать. **Сообщение об ошибке, передаваемое боту** - сообщение, которое будет получать Савви от действия, в случае, если на стороне веб-хука вернется ошибка. Может быть пустым, в этом случае Савви получит текст ошибки от URL-адреса, на который отправляется веб-хук. {% endstep %} {% step %} ### Настройка раздела "Дополнительные настройки"
**Действия при вызове** — в этом разделе мы отмечаем флаги тех настроек, которые нам требуются, а именно: **Добавить задержку перед вызовом** — полезно при работе с CRM, если на стороне интеграции выполняется какая-то автоматизация **Остановить диалог при вызове** — при вызове функции ействия, бот прерывается **Не отвечать при вызове** — бот не напишет ответ клиенту, вызовется только функция\ **Присвоить тег при вызове** — при вызове функции диалогу присвоится тег, который Вы пропишете
**Действия при ошибке** — настройки, которые сработают в случае ошибки действия **Уведомлять при ошибке** — Если в процессе выполнения действия возникнет ошибка, то пользователь получит уведомление **Останавливать диалог при ошибке** — если действие выполнится с ошибкой, то диалог с ботом остановится. **Сообщение об ошибке, передаваемое боту** — если действие выполнится с ошибкой, то в самой функции вернётся тот текст, который пропишет пользователь, например An error occured
**Результат, возвращаемый боту** — здесь мы можем выбрать то, что вернётся боту в результате выполнения функции, есть четыре варианта:
Настраиваемый результат позволяет вернуть настроенные переменные. Для этого, нужно нажать на колёсико справа от окна, в котором прописываем кастомизированный результат:
{% endstep %} {% endstepper %} ## Настройки веб-хука ### Название, URL и метод **Название** - название для отображения в списке шагов. **URL** - сюда указывается адрес на стороне куда будет передаваться запрос. Это может быть как **IP-адрес**, так и доменное имя, например, `https://192.168.34.12` или `https://test.ru` *(тут будет какой-то ваш нужный адрес).* **Метод запроса** - метод отправляемого запроса (GET, POST и т.д.). Этот метод должна предоставлять конечная сторона. Подробнее о разных методах, можно посмотреть [здесь](https://developer.mozilla.org/ru/docs/Web/HTTP/Methods). ### **Параметры, которые будут передаваться в URL** **Параметры, которые будут передаваться в URL** - это те параметры, которые обычно в адресе передаются после знака ?. > Например: > > > > Где, phone и date - это параметры В форме шага данный пример будет выглядеть так:
Но в данном случае, мы передали фиксированные значения. А как сделать, когда эти величины являются изменяемыми и у каждого клиента / диалога они будут свои? Для этого используются **переменные**. #### Использование переменных (аргументы действия) Переменные мы указывали на предыдущем шаге, когда добавили их в форме действия, теперь нам осталось их просто выбрать через кнопку **+**. Для выше описанного примера, когда нам нужно указать изменяемые параметры, мы делаем так:
При этом, несмотря на то, что мы рекомендуем делать подробное описание, боту даже не обязательно описывать дополнительные инструкции о том, какие параметры ему нужно запросить у клиента, он и так это поймет. Поэтому названия переменных лучше выбирать понятные. {% hint style="info" %} В URL-адресе так же можно указывать переменные, когда они в явном виде не являются параметрами, например, так: Где phone будет автоматом заменяться на телефон присаланный клиентом. {% endhint %} ### Заголовки запроса В заголовках запроса часто передается информация об авторизации. Это скорее статические параметры, но иногда могут передаваться и динамические параметры, какие-либо ключ шифрования, которые получены на предыдущем шаге.
### Отправка запросом с данными (POST, PUT, DELETE, PATCH) В случае с отправкой POST, PUT, DELETE и PATCH запросов появляется поле, в котором указывается тело запроса. У нас реализовано два типа тела - это текст и JSON. Для того, чтобы при отправке не возникало ошибок, требуется соблюдать определенные правила синтаксиса. Элементы JSON должны быть в кавычках. Переменные так же выбираются нажатием на **+**. На примере выше рассмотренного примера, тело запроса будет выглядеть так:
{% hint style="info" %} Не забывайте про кавычки при использовании **JSON**, даже при использовании переменных. {% endhint %} ### Статус коды Можно указать статус коды, на которые бот будет реагировать. По умолчанию ставится код 200, т.е. код успешного возврата. В случае не успеха, бот получит текст, написанный в поле **"Сообщение об ошибке"** из настроек действия. Можно убрать отбор на статус коды - и тогда он будет видеть все статусы и все ошибки, которые ему возвращаются и выдавать их клиенту. ### Правила ответа боту
Поскольку, как мы говорили ранее, мы можем передавать последовательность шагов, в том числе в виде веб-хуков за один раз, то есть настройка, которая определяет, а что мы передадим боту в ответ: * **Все** - передадим все ответы с каждого шага * **Только первый** - только ответ от первого шага * **Только последний** - только ответ с последнего шага По умолчанию, ставится ответ с последнего шага, что кажется логичным. Хотя, конечно, бывают сценарии в которых мы можем передать информацию с первого шага и дальше выполнить ряд служебных действий, ответ от которых мы не передаем клиенту, например, когда мы просто оповещаем сторонние системы о каком-то триггере. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.suvvy.ai/ru/deistviya/veb-khuki.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.