Что такое вебхук и как его создать
Вебхук — это механизм для передачи автоматических уведомлений и данных между сервисами при наступлении определенных событий.
Используя вебхуки в 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 запроса. Сделано для визуализации и не требует редактирования.
Количество попыток отправки
По умолчанию вебхук отправляется не более одного раза. При технических неполадках эта единственная попытка отправки может быть утеряна и даже не залогирована.
Но, если добавить в вызов параметр с ключом идемпотентности ${WebhookRequest.TransactionalId}, то при получении в ответе ошибок 5xx и 429 вебхук будет повторно вызван три раза в течение 6 минут. При получении других кодов ответов или при отсутствии параметра, повторных попыток подключения не произойдет.
Чтобы обеспечить однократное выполнение, при повторном обращении с уже обработанным запросом нужно давать тот же ответ, что и при первом.
Параметр не является обязательным.
Как добавить transactionId
Ключ идемпотентности можно ввести в адрес, заголовок или тело запроса.
Уточняйте в документации используемого сервиса, принимает ли он параметр transactionId и в каком виде его нужно передавать в вебхуках, так как требования к формату данных в сервисах могут различаться.
Рассмотрим примеры передачи transactionId в URL вебхука.
Параметр transactionId=${WebhookRequest.TransactionalId} добавляется после вопросительного знака ? кликом по соответствующей кнопке:
Множественные параметры разделяются амперсандом &:
2.3. Заголовки.
-
Унаследованные из интеграции — заголовки, которые были указаны в интеграции. Можно исключить ненужные, убрав галочку «Использовать».
-
Добавленные — заголовки, которые добавляются для конкретного вебхука.
При вызове используются и унаследованные и добавленные заголовки.
В данном примере итоговый набор заголовков:
Content-Type:application/jsonwebhookHeader:test
2.4. Тело запроса.
В теле запроса можно использовать параметры шаблонизатора, в том числе блоки if-else if-end if и циклы for-end for.
Параметры передаются с помощью JSON-кода.
Из правой боковой панели можно перейти в справку по шаблонизатору.
2.5. Ответ вебхука.
Нужно включить при использовании ответа вебхука в сценарии.
Можно принимать как сам факт успешной доставки вебхука, так и конкретные значения из ответа вебхука.
Пример записи переменной:
Подробнее об использовании ответов вебхуков — в статье.
3. Нажмите «Сохранить»:
Полезные ссылки:
Чтобы клонировать вебхук, откройте меню нужного вебхука и нажмите «Копировать»:
