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

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

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

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

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

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

   

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

   

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

   • Введите название.

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

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

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

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

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

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

     

   • Заголовки.

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

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

     

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

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

Статические IP-адреса для отправки вебхуковСтатические IP-адреса для отправки вебхуков

Использование статических IP-адресов для отправки вебхуков позволит ограничить доступ к вашим системам только проверенными источниками. Это создаст дополнительный уровень защиты от DDoS-атак и других вредоносных действий.

1. Включите модуль «Статические IP-адреса для отправки вебхуков».

2. Перейдите в раннее созданную точку интеграции для вебхуков или создайте новую.

   Нажмите «Изменить» в общих настройках → переключите тумблер «Отправлять вебхуки через статические IP-адреса» → сохраните изменения. Обратите внимание, что нужно сохранить изменения не только в общих настройках, но и в самой точке интеграции.

   

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

3. Скопируйте доступные адреса и пропишите их в список разрешенных в вашем сервисе.

Просмотр доступных адресов доступен только персоналу с правом «Управление секретными данными».

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

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

   

   

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

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

   • Общие настройки:

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

Количество попыток отправкиКоличество попыток отправки

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

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

• Временные сетевые ошибки;
• Потеря ответа от сервера получателя;
• Таймауты;
• Технические сбои;
• Штатная работа системы. Например, в случаях, когда Mindbox не получил подтверждение доставки.

Пример корректной отправки вебхука: Mindbox отправляет вебхук → сервер получателя успешно обрабатывает его.

• Если сервер возвращает статус Success (200 ОК) — вебхук считается успешно доставленным и повторная отправка не происходит.
• В случаях, когда происходит таймаут из-за медленного ответа сервера или ответ со статусом Success не поступает из-за потери данных в сети — система решает, что запрос не был доставлен и отправляет вебхук повторно, несмотря на фактический успех первой попытки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

Сохраните изменения:

---

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

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

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