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

Вебхук - это механизм, с помощью которого можно вызывать произвольные http -сервисы при наступлении определённых событий.
Более простым языком — механизм оповещения системы о событиях.

• Вебхук нужен для передачи информации от mindbox к внешней системе
• Инициатором в отправке вебхука выступает mindbox
• ТЗ на вебхук подготавливается заказчиком
• Вебхук используется в шаге сценария

Например, его можно использовать для:

— отправки в call центр информации о новом заказе или его изменение
— оповещения персонала о негативной оценке клиента
— синхронизировать подписки
— и т.д.

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

Верхнеуровнево вебхук состоит из трех частей:

— адрес, к которому он обращается

— заголовки (отвечают за метод/авторизацию и тд.)

— тело (данные, которые мы передаем)

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

Управление вебхуками находится в меню Интеграции —> Вебхуки

Для создания нового вебхука нажмите кнопку «Добавить»:

Заполним поля:

1. Имя — название вебхука, которое отобразится в настройках сценария.

2. Метод — выбираем в зависимости от задачи: GET, POST или PUT
   Более подробно почитать о методах можно здесь.

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

пример итогового URL

Если добавить параметр ${WebhookRequest.TransactionalId} в адрес, заголовок или тело запроса, то параметр будет присваивать ID запросу вебхука.
Вебхук будет повторно подключаться в течение 3 дней, пока не отработает успешно (код 200).
Если этого параметра нет — повторных попыток подключения не произойдет.

Например:в базу попал новый адрес почты и мы хотим передать его во внешнюю систему (id запроса = 1), но в момент передачи произошла ошибка и запрос не отработал.
Без TransactionalId внешняя система не знает, был ли такой запрос или нет. В итоге мы не можем его повторить (ведь все запросы без идентификаторов, как отличить один от другого), в итоге данные потеряны.
С TransactionalId внешняя система смотрит и видит, что вебхука с id 1 еще не было, а значит это новые данные, их нужно сохранить.
Итог — данные не потеряны

4. Заполняем заголовки — заголовков может быть несколько:

5. Заполняем тело запроса для метода POST — в теле запроса можно перечислить любые параметры из системы, доступен код JSON, поэтому условия (if) допускаются

Доступна Справка по шаблонизатору, если есть сомнения в названии полей

6. Нажимаем на кнопку «Сохранить изменения»

Ошибки, где смотреть

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

Нажимаем на значок «молнии» в нижнем левом углу:

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

Краткая статья в разделе для разработчиков