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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Из правой боковой панели можно перейти в справку по шаблонизатору.

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

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

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

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

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

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

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

• Статья о вебхуках для разработчиков
• Экспорт логов вебхуков

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