О механике

Зачем нужны вебхуки

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

В каких случаях использовать вебхук, а в каких — публичный API

Получать уведомления об изменениях на платформе можно двумя способами — через публичный API и вебхуки. Механики этих методов отличаются, поэтому они могут использоваться для разных целей:

• С помощью публичного API данные запрашиваются вручную: администратор периодически отправляет запрос и проверяет, появились ли изменения. Это подойдёт для редких событий, которые важно проверять по расписанию

• С помощью вебхуков система автоматически уведомляет об определённых изменениях. Это удобно для непредвиденных событий, когда нужно реагировать моментально (например, изменился статус учебного материала)

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

Как выглядит общий процесс работы с вебхуками на стороне Motivity

1. Администратор создаёт и активирует вебхук по определённому триггеру на платформе

2. На платформе происходит событие, инициирующее срабатывание триггера

3. Для каждого пользователя, для которого наступило событие, формируется отдельный POST-запрос

   • Тип application/json, параметр header и соответствующее ему значение передаются в заголовке, если были указаны в настройках триггера

4. Запрос уходит на ранее указанный адрес

5. В теле запроса отправляется сообщение из поля JSON-запрос для триггера

   • Если в нём использовались переменные, они заменяются на соответствующие значения для каждого пользователя

   • Если переменная не заполнена в базе данных, отправляется null

   • Если переменная указана некорректно (такая переменная не существует или не поддерживается для конкретного запроса), при попытке сохранить вебхук выводится ошибка и сохранение не происходит

6. Информация о запросе и ответе логируется в Панели управления → Логи → Лог исходящих вебхуков

7. Запрос отправляется однократно, вне зависимости от полученного ответа

   • Если было создано несколько вебхуков с одним триггером, запрос формируется для каждого из них

   • Вебхук отправляется, даже если уведомление с соответствующим триггером отключено в Панели управления → Уведомления → Центр уведомлений. На отправку вебхука влияет только выключение активности непосредственно в его настройках

Для администратора

Как настроить доступ к вебхукам

Доступ для администратора

Настроить доступ для администратора можно в Панели управления → Пользователи → Роли → Общие разрешения → Уведомления.

Доступ для другой роли пользователей

Чтобы настроить доступ к модулю для конкретной роли, выполните следующие действия:

1. Перейдите в Панель управления → Пользователи → Роли

2. Выберите роль из списка или добавьте новую по кнопке Добавить

3. На странице редактирования роли перейдите во вкладку Разрешения → [Название модуля] и включите необходимые функции

4. Во вкладке Пользователи проверьте, что роль присвоена всем планируемым пользователям

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

Как добавить и настроить вебхук

Чтобы добавить вебхук, перейдите в Панель управления → Уведомления → Вебхуки и нажмите кнопку Добавить. Откроется страница, на которой можно задать основные настройки:

Настройки названия и показа вебхука

• Название* — обязательное поле. Максимум 250 символов

• Включить вебхук — установите или снимите , чтобы включить или выключить вебхук на платформе

Настройки запроса и параметра

• Ссылка* — обязательное поле. Укажите адрес, по которому должен отправляться POST-запрос при срабатывании триггера

• Название параметра для заголовка запроса — это поле может использоваться для передачи токена безопасности (например, API Key) или в других целях

• Значение параметра для заголовка запроса — добавьте значение, которое передаётся в указанном заголовке header

Настройки триггера и JSON-запроса

• Триггер* — обязательное поле. Выберите один вариант из списка, после сохранения вебхука изменить его нельзя

• JSON-запрос для триггера* — обязательное поле. Подставляется автоматически для выбранного триггера

  • Пример JSON-запроса для триггера Библиотека. Публикация нового материала

  • { "trigger": $trigger, "user": $user, "file": $file, "directory": $directory }

Как работать со списком вебхуков

Необязательно заходить на страницу редактирования каждого вебхука, чтобы проверить настройки. Для этого перейдите в список вебхуков в Панели управления → Уведомления → Вебхуки и изучите:

• Активность — отображается как цвет ID:

  • Зелёный — активен

  • Серый — неактивен

  • Красный — удалён

• Название

• Триггер

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

Остальные настройки доступны на странице создания/редактирования вебхука — Вебхуки | Как добавить и настроить вебхук

Для каких модулей можно настроить вебхук

Логирование

Подробно о логировании вебхуков — https://motivityy.atlassian.net/wiki/spaces/Documentation/pages/5734464#%D0%9B%D0%BE%D0%B3-%D0%B8%D1%81%D1%85%D0%BE%D0%B4%D1%8F%D1%89%D0%B8%D1%85-%D0%B2%D0%B5%D0%B1%D1%85%D1%83%D0%BA%D0%BE%D0%B2