Что такое вебхук и как его создать
  • 03 May 2024
  • 2 минуты
  • Темная тема
    Светлая тема
  • формат pdf

Что такое вебхук и как его создать

  • Темная тема
    Светлая тема
  • формат pdf

Вводный текст

Вебхук — это механизм для передачи автоматических уведомлений и данных между сервисами при наступлении определенных событий.

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

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

Создание точки интеграции

  1. Перейдите в раздел Интеграции и нажмите «Добавить интеграцию»:

ima

  1. Выберите пресет «Интеграция для вебхуков»:

Снимок экрана 2023-06-07 в 20.08.44.png

  1. Настройте интеграцию.

3.1. Введите название.
3.2. Общие настройки.

  • URL — корневой URL, который будет использоваться в вебхуках. Формируется на стороне заказчика. Можно задать ссылку целиком или указать общую корневую часть, а в каждом конкретном вебхуке вписывать только уникальные части ссылки.

Например, корневой URL Mindbox — https://api.mindbox.ru/v3/operations/, а запросы к сервису отличаются. В таком случае в интеграции можно задать общую для всех вебхуков часть, а в каждом конкретном вебхуке уже указывать только уникальный id.
Снимок экрана 2023-06-07 в 20.44.09.png

  • Скорость отправки запросов в секунду — можно задать допустимый максимум.
    Полезно для сервисов, которые могут обрабатывать ограниченное количество запросов в секунду.

Лимит общий для всех вебхуков данной интеграции.

Обратите внимание, что ограничение на количество одновременных запросов — приблизительное, так как фактическое число вызовов в секунду может меняться в зависимости от задержек сети. Рекомендуем указывать меньшую скорость, чем может обрабатывать сервис, чтобы снизить вероятность превышения порога.

Снимок экрана 2023-06-08 в 06.54.16.png

3.3. Заголовки.

Задайте нужные для сервиса заголовки. Чаще всего используются: авторизация (Authorization), формат данных (Content-Type).

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

Снимок экрана 2023-06-08 в 06.56.24.png

  1. Нажмите «Сохранить».

После этого будет доступно создание вебхуков по интеграции:

Снимок экрана 2023-06-08 в 06.57.36.png

Создание вебхука

  1. Добавьте вебхук со страницы интеграции или перейдя в раздел Интеграции -> Вебхуки:

Снимок экрана 2023-06-08 в 07.19.29.png

Снимок экрана 2023-06-08 в 07.19.58.png

  1. Настройте вебхук.

2.1. Задайте название вебхука.

Оно будет отображаться в списке механик и в шагах сценария.

2.2. Общие настройки.

  • Системное имя — используется для обработки ответа вебхука. Значение должно быть уникальным.
  • Описание — любая полезная информация о функции вебхука. Опциональное поле.
  • Метод — в зависимости от задачи: GET, POST, PUT, PATCH, DELETE.
  • Корневой URL — URL из интеграции.
  • URL — дополнение к корневому URL, указанному в интеграции. Может не заполняться, если интеграция содержит полный адрес.
  • Просмотр URL — вывод полного URL запроса. Сделано для визуализации и не требует редактирования.
Ключ идемпотентности

Если добавить в вызов параметр ${WebhookRequest.TransactionalId}, то при получении в ответе ошибок 5xx и 429 вебхук будет повторно вызван три раза в течение 6 минут. При получении других кодов ответов или при отсутствии параметра, повторных попыток подключения не произойдет.

Чтобы обеспечить однократное выполнение, при повторном обращении с уже обработанным запросом нужно давать тот же ответ, что и при первом.

Параметр не является обязательным.

Снимок экрана 2023-11-16 в 17.43.50.png

Как добавить transactionId

Ключ идемпотентности можно ввести в адрес, заголовок или тело запроса.

Уточняйте в документации используемого сервиса, принимает ли он параметр transactionId и в каком виде его нужно передавать в вебхуках, так как требования к формату данных в сервисах могут различаться.

Рассмотрим примеры передачи transactionId в URL вебхука.

Параметр transactionId=${WebhookRequest.TransactionalId} добавляется после вопросительного знака ? кликом по соответствующей кнопке:

Снимок экрана 2023-11-16 в 17.45.15.png

Множественные параметры разделяются амперсандом &:

Снимок экрана 2023-11-16 в 17.40.27.png

2.3. Заголовки.

  • Унаследованные из интеграции — заголовки, которые были указаны в интеграции. Можно исключить ненужные, убрав галочку «Использовать».

  • Добавленные — заголовки, которые добавляются для конкретного вебхука.

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

Снимок экрана 2023-06-08 в 07.56.03.png

В данном примере итоговый набор заголовков:

  • Content-Type:application/json
  • webhookHeader:test

2.4. Тело запроса.

В теле запроса можно использовать параметры шаблонизатора, в том числе блоки if-else if-end if и циклы for-end for.
Параметры передаются с помощью JSON-кода.

Снимок экрана 2023-06-08 в 08.51.20.pngИз правой боковой панели можно перейти в справку по шаблонизатору.

2.5. Ответ вебхука.

Нужно включить при использовании ответа вебхука в сценарии.

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

Пример записи переменной:

Снимок экрана 2023-06-08 в 09.10.05.png

Подробнее об использовании ответов вебхуков — в статье.

  1. Нажмите «Сохранить»:

Снимок экрана 2023-06-08 в 09.12.11.png


Полезные ссылки:

Чтобы клонировать вебхук, откройте меню нужного вебхука и нажмите «Копировать»:

Снимок экрана 2023-07-22 в 12.08.02.png

Что такое вебхуки и как они используются, где их можно настроить, примеры использования в Mindbox.