Настройка интеграции вебхуков

Вебхуки — инструмент для получения данных от сторонних сервисов. Как администратор BPMSoft, вы можете настроить автоматическое реагирование на запросы для мгновенного запуска бизнес-процессов и действий над объектами.

Алгоритм настройки

Конфигурация пользовательских вебхуков в BPMSoft осуществляется с помощью инструментов low-code, что значительно упрощает настройку и использование.

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

• Дизайнер системы → блок «Импорт и интеграции» → раздел «Настройка вебхуков»;
• Дизайнер системы → блок «Конфигурирование разработчиком» → Управление конфигурацией → перейти в пользовательский пакет → добавить элемент «Вебхук».

Общая процедура настройки вебхука включает следующие шаги:

1. Создание и настройка вебхука.
2. Настройка аутентификации.
3. Добавление и настройка параметров метода вебхука.
4. Настройка действия, которое выполняется при получении вебхука.

Создание и настройка вебхука

Для создания нового вебхука выполните следующие действия:

1. В разделе «Вебхуки» нажмите на кнопку «Добавить вебхук».
2. Заполните свойства вебхука, описанные в таблице ниже.

Таблица 1 — Свойства вебхука

Рисунок 1 — Свойства вебхука

Настройка аутентификации

Для выполнения методов вебхука существует три способа аутентификации:

1. Анонимная аутентификация.
2. Forms-аутентификация.
3. JWT-аутентификация.

Анонимная аутентификация

Включение анонимной аутентификации уменьшает безопасность BPMSoft. Это связано с тем, что неавторизованные пользователи могут выполнять запросы на добавление, изменение. Не рекомендуем использовать данный режим при реализации интеграций.

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

По умолчанию анонимная аутентификация отключена.

Для включения анонимной аутентификации необходимо выполнить следующие действия:

1. В конфигурационном файле внесите следующие изменения:

• Для .NET Framework — в файле WebApp/Web.config у параметра с ключом UseWebhookAnonymousAuth измените значение value на true;
• Для .NET 8 — в файле BPMSoft.WebHost.dll.config у параметра с ключом UseWebhookAnonymousAuth измените значение value на true.

2. Перезапустите приложение.
3. На странице вебхука перейдите на вкладку «Аутентификация» и в поле «Тип аутентификация» выберите значение «Не требуется».
4. Нажмите кнопку «Сохранить».

В результате выполнения данных настроек методы вебхука станут доступны для вызова без аутентификации.

Включение анонимной аутентификации доступно только при развертывании on-site.

Forms-аутентификация

Для того чтобы методы вебхука были доступны для вызова через forms-аутентификацию, выполните следующие действия:

1. На странице вебхука перейдите на вкладку «Аутентификация» и в поле «Тип аутентификация» выберите значение «Cookie».
2. Выберите пользователя в поле «Пользователь для авторизации», через которого будет выполняться forms-аутентификация для доступа к методам вебхука.

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

После сохранения методы вебхука станут доступны для вызова при передаче специального cookie в заголовках последующих запросов. Подробнее: Forms-аутентификация.

JWT-аутентификация

Для того чтобы методы вебхука были доступны для вызова с помощью передачи JWT-токенов, выполните следующие шаги:

1. В конфигурационном файле внесите следующие изменения:
• Для .NET Framework — в файле WebApp/Web.config у параметра с ключом WebhookSecretKey в качестве значения value внесите секретный ключ для генерации JWT-токена;
• Для .NET 8 — в файле BPMSoft.WebHost.dll.config у параметра с ключом WebhookSecretKey в качестве значения value внесите секретный ключ для генерации JWT-токена.

• Используйте ключ длиной не менее 32 символов, который включает буквы в верхнем и нижнем регистре, цифры и специальные символы;
• В качестве ключа подойдут GUID, случайная последовательность символов или данные, сгенерированные специализированными инструментами для создания секретных ключей.

2. Перезапустите приложение.
3. На странице вебхука перейдите на вкладку «Аутентификация» и в поле «Тип аутентификация» выберите значение «JWT».
4. Выберите пользователя в поле «для авторизации», через которого будет выполняться аутентификация с помощью JWT-токена для доступа к методам вебхука.

5. В поле «Действителен до» укажите срок действия токена.
6. Если требуется, то заполните поле «Заголовок запроса для токена». Если заголовок запроса для токена не заполнен, то его значение будет равно «Authorization».
7. Нажмите кнопку «Сохранить».

Рисунок 2 — Тип аутентификации «JWT»

После сохранения вебхука кнопка «Сгенерировать токен» станет активной. Для генерации токена:

1. Нажмите на кнопку «Сгенерировать токен».
2. Откроется модальное окно, где в текстовом поле будет расположен сгенерированный JWT-токен.
3. Нажмите кнопку «Скопировать токен».

Рисунок 3 — Модальное окно генерации JWT-токена

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

4. Нажмите кнопку «Закрыть», чтобы скрыть модальное окно.

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

После сохранения методы вебхука станут доступны для вызова при передаче JWT-токена в заголовках последующих запросов.

Уведомления об истечении срока действия JWT-токена

Срок действия токена устанавливается в поле «Действителен до». В коммуникационной панели появится уведомление о скором истечении срока действия токена в следующие периоды:

• За 30 дней;
• За 15 дней;
• За сутки.

После истечения срока действия токена уведомление будет приходить через день в течении двух недель. Рекомендуем обновить токен до окончания срока его действия.

Методы вебхука

Для создания метода вебхука выполните следующие шаги:

1. Откройте вебхук.
2. Во вкладке «Методы вебхука» нажмите на кнопку +.
3. Заполните свойства метода вебхука, описанные в таблице ниже.

Таблица 2 — Свойства метода вебхука

Рисунок 4 — Пример заполнения метода вебхука

4. Добавьте параметры метода.
5. Добавьте действия при получении вебхука.
6. Нажмите на кнопку «Готово».
7. Сохраните вебхук, нажав на кнопку «Сохранить».
8. В детали «Методы вебхука» выберите добавленный метод и нажмите на кнопку «Опубликовать».
9. Повторно сохраните вебхук, нажав на кнопку «Сохранить».

Рисунок 5 — Деталь «Методы вебхука»

После публикации метод станет доступен для вызова из внешней системы.

Параметры метода

В метод вебхука можно добавить следующие виды параметров:

• Параметры запроса;
• Параметры ответа.

Параметры запроса

Параметры запроса принимаются на вход вебхуком при его вызове из внешней системы.

Для добавления параметра запроса выполните следующие шаги:

1. Откройте метод вебхука.
2. Перейдите на вкладку «Параметры запроса».
3. Нажмите на кнопку «Добавить параметр».
4. Заполните свойства параметра запроса.

Таблица 3 — Свойства параметра запроса

Рисунок 6 — Пример заполнения параметра запроса

5. Сохраните параметр запроса, нажав на кнопку «Готово».
6. Сохраните метод вебхука, нажав на кнопку «Готово».
7. Сохраните вебхук, нажав на кнопку «Сохранить».

Параметры ответа

Параметры ответа возвращаются вебхуком после успешного выполнения запроса из внешней системы.

Для добавления параметра ответа выполните следующие шаги:

1. Откройте метод вебхука.
2. Перейдите на вкладку «Параметры ответа».
3. Нажмите на кнопку «Добавить параметр».
4. Заполните свойства параметра ответа.

Таблица 4 — Свойства параметра ответа

5. Сохраните параметр ответа, нажав на кнопку «Готово».
6. Сохраните метод вебхука, нажав на кнопку «Готово».
7. Сохраните вебхук, нажав на кнопку «Сохранить».

Быстрая настройка

Для автоматического добавления параметров запроса или ответа выполните следующие шаги:

1. Перейдите в метод вебхука.
2. Перейдите на вкладку «Параметры запроса» или «Параметры ответа» — в зависимости от ваших потребностей.
3. Нажмите на кнопку «Быстрая настройка».
4. Введите JSON-код примера объекта запроса или ответа.

Например:

{
	"name": "testName",
	"age": 18
}

5. Нажмите кнопку «Далее».

После выполнения быстрой настройки в выбранной вкладке будут добавлены параметры. По вышеприведенному примеру добавится два параметра:

Таблица 5 — Параметры, добавленные быстрой настройкой

Действия при получении вебхука

Для добавления действий, которые будут выполнены при вызове вебхука, выполните следующие шаги:

1. Перейдите в метод вебхука.
2. Перейдите на вкладку «Действия при получении вебхука».
3. Нажмите на кнопку «Добавить действие при получении вебхука».
4. Заполните свойства действия при получении вебхука.

Таблица 6 — Свойства действия при получении вебхука

5. В зависимости от выбора в поле «Тип действия»:
   1. Если выбран «Тип действия» = «Выполнить БП»:
      • В поле «Название БП» выберите бизнес-процесс, который будет выполняться при вызове метода вебхука;
      • В блоке «Параметры бизнес процесса» рядом с параметром нажмите на поле, чтобы выбрать параметр запроса, значение которого необходимо передать в качестве входящего параметра выбранного бизнес-процесса;
      • В блоке «Параметры БП для ответа» рядом с параметром нажмите на поле, чтобы выбрать параметр ответа, в который необходимо сохранить исходящий параметр бизнес-процесса.
   2. Если выбран «Тип действия» = «Изменить данные»:
      • В поле «Название объекта» выберите объект, у записей которого необходимо изменить значения колонок;
      • В поле «Результат изменения данных» выберите параметр ответа, в который будет записываться массив с Id измененных записей;
      • В блоке «Колонки для обновления объекта» рядом с названием колонки нажмите на поле, чтобы выбрать параметр запроса, значение которого необходимо использовать в качестве нового значения выбранной колонки объекта;
      • В блоке «Колонки для поиска объекта» рядом с названием колонки нажмите на поле, чтобы выбрать параметр запроса, значение которого необходимо использовать в качестве фильтра для поиска.
   3. Если выбран «Тип действия» = «Добавить данные»:
      • В поле «Название объекта» выберите объект, в который нужно добавить запись;
      • В блоке «Колонки для добавления объекта» рядом с названием колонки нажмите на поле, чтобы выбрать параметр запроса, значение которого необходимо использовать в качестве значения выбранной колонки объекта;
      • В блоке «Колонки объекта для ответа» рядом с названием колонки нажмите на поле, чтобы выбрать параметр ответа, в который необходимо сохранить значение выбранной колонки созданной записи.

6. Сохраните действие при получении ответа, нажав на кнопку «Готово».
7. Сохраните метод вебхука, нажав на кнопку «Готово».
8. Сохраните вебхук, нажав на кнопку «Сохранить».

Рисунок 7 — Действие при получении вебхука

Логирование

В вебхуке можно отслеживать события, связанные с его использованием.

Таблица 7 — Логируемые признаки

Свойство «Логирование тела вебхука» возможно использоваться только после включения свойства «Логирование вебхука».

Рекомендуем изучить

Возможности интеграции
Выполнить запрос в Postman с авторизацией вручную
Анализ проблем с вебхуками