ym88659208ym87991671
Вебхуки | Документация для разработчиков

Вебхуки

Обновлено 13 мая 2024

Вебхук — это способ, с помощью которого можно обращаться к подсистемам смартапа, реализованным на любых языках программирования и размещенным на сторонних серверах. Подсистемы производят вычисления для определенных задач и возвращают смартапу переменные, необходимые для работы сценария.

При использовании вебхука ассистент перед переходом к выполнению блоков экрана передаст все переменные на ваш сервер и будет ждать ответа.

Получив ответ, асисстент обновит значения переменных и перейдет к выполнению блоков.

Таким образом использование вебхуков позволяет дополнять и изменять переменные в процессе работы смартапа.

Используйте вебхуки, если вашему смартапу необходимо часто вычислять или сохранять данные и строить диалог с пользователем с учетом них. В этом случае вы сможете делать сложные вычисления и интеграции на собственном сервере, используя при этом любой язык программирования.

Вы также можете использовать блок HTTP-запрос, если для работы смартапа нужны небольшие вычисления или сохранение небольших объемов данных.

Включение вебхуков

Адрес вебхука может быть публичным или тестовым:

  • вебхуки, развернутые на публичных адресах, работают с опубликованными смартапами;
  • вебхуки, развернутые на тестовых адресах, помогают проводить диагностику и отладку в процессе разработки смартапа.

Сообщения, которыми ассистент обменивается со сторонним вебхуком, соответствуют протоколу вебхуков Graph.

Сервер для вебхука можно разрабатывать локально, а затем загружать код на публичный сервер. Например, с помощью ngrok .

Чтобы включить сторонние вебхуки:

  1. В левой навигационной панели проекта нажмите Настройки. Откроется окно Настройки сценария SmartApp.
  2. На вкладке Базовые настройки в блоке Настройки вебхука укажите в зависимости от настраиваемого вебхука адрес в поле Публичный или Тестовый.
  3. Нажмите кнопку Сохранить.

Отправка вебхуков

Чтобы отправлять вебхуки:

  1. Выберите экран, с которого необходимо отправлять вебхуки.

  2. В названии экрана укажите имя события, которое будет передаваться на сторонний сервер.

    Например event1.

  3. Нажмите на кнопку вебхука в правом верхнем углу экрана.

Смартап будет отправлять переменные и выбранное событие на сервер, а затем копировать переменные из ответа сервера. Только после этого смартап будет выполнять блоки на экране.

Переменные, полученные от вашего сервера, можно использовать точно так же, как и любые другие – например подставлять в текстовый ответ, использовать в условиях или в HTTP-запросах.

События вебхука

На каждом экране, где надо вызывать вебхук, требуется указать событие.

Событие – это любая строка текста, которая будет передана вебхуку вместе с переменными. Событие показывает серверу, с какого экрана пришел запрос, и какие данные надо вернуть.

События задаются в названии экрана и могут быть представлены в виде произвольного текста.

Разные экраны могут иметь одинаковые события.

Протокол вебхуков Graph

На каждом экране, где включено событие для вебхука, ассистент посылает POST-запрос, в теле которого передает JSON-объект. Этот объект содержит все текущие переменные смартапа (в том числе системные), а также поле action – текст события, заданное в названии экрана.

Пример:

{
"action": "event1",
"queryText": "пока",
"userId": "1234567890",
"rawRequest": {"message": {...}},
"variable1": 50,
"variable2": "значение"
}

Ассистент ожидает от сервера JSON-объект с переменными, которые смартап использует в блоках экрана.

Пример:

{
"lastSeen": 60,
"name": "Василий",
"data": {
"age": 30,
"website": "http://example.com"
}
}

В этом примере сервер вебхука вернул переменные lastSeen, name и data. Теперь смартап может их использовать в своем сценарии, начиная с того экрана, на котором он получил эти переменные.

Отличие вебхука от блока HTTP-запрос

Можно использовать блок HTTP-запрос всякий раз, когда смартапу надо получить данные от вашего сервера.

При этом вебхук обладает следующими преимуществами, если необходимо делать запросы более чем с одного экрана:

  • Сценарий не перегружается блоками HTTP-запрос, что делает его более понятным.
  • Вебхук всегда отправляет все текущие переменные на один адрес, заданный в настройках смартапа.
  • Протокол вебхука стандартизирован, и смартап самостоятельно скопирует все переменные из ответа.
  • Вебхук можно включать или выключать на разных экранах.
  • Вебхук можно разрабатывать и отлаживать на непубличном тестовом адресе.

Где бесплатно развернуть вебхук

Чтобы запустить вебхук, необходим хостинг.

При этом во время разработки вы можете использовать такие утилиты, как ngrok , чтобы на время получить публичный адрес, который позволит серверу на вашем локальном компьютере получать запросы от вашего смартапа.

Для бесплатного публичного размещения сервера для обработки вебхуков можно рассмотреть платформу heroku.com . Она позволяет создавать серверы на любом языке программирования.

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.