#Интеграция Webhook в рабочий процесс

С помощью триггеров Webhook NocoBase может принимать HTTP-вызовы от сторонних систем и автоматически запускать рабочие процессы, обеспечивая бесшовную интеграцию с внешними системами.

#Обзор

Webhook — это механизм "обратного API", который позволяет внешним системам активно отправлять данные в NocoBase при возникновении определенных событий. По сравнению с активным опросом (polling), Webhook обеспечивает более оперативную и эффективную интеграцию.

#Типичные сценарии использования

#Отправка данных форм

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

#Уведомления о сообщениях

События из сторонних мессенджеров (таких как WeCom, DingTalk, Slack), например, новые сообщения, упоминания или завершение согласования, могут запускать автоматизированные рабочие процессы в NocoBase через Webhook.

#Синхронизация данных

При изменении данных во внешних системах (например, CRM, ERP) Webhook в реальном времени передает обновления в NocoBase для поддержания синхронизации данных.

#Интеграция со сторонними сервисами

• GitHub: Отправка кода, создание запросов на слияние (PR) и другие события запускают автоматизированные рабочие процессы.
• GitLab: Уведомления о статусе конвейеров CI/CD.
• Отправка форм: Внешние системы форм отправляют данные в NocoBase.
• Устройства IoT: Изменения статуса устройств, передача данных с датчиков.

#Возможности

#Гибкий механизм запуска

• Поддерживает методы HTTP: GET, POST, PUT, DELETE.
• Автоматически анализирует (парсит) JSON, данные форм и другие распространенные форматы.
• Настраиваемая проверка запросов для обеспечения доверия к источникам.

#Возможности обработки данных

• Полученные данные могут использоваться в рабочих процессах как переменные.
• Поддерживает сложную логику преобразования и обработки данных.
• Может комбинироваться с другими узлами рабочего процесса для реализации сложной бизнес-логики.

#Обеспечение безопасности

• Поддерживает проверку подписи для предотвращения поддельных запросов.
• Настраиваемый белый список IP-адресов.
• Шифрованная передача данных по HTTPS.

#Шаги использования

#1. Установка плагина

Найдите и установите плагин Рабочий процесс: Webhook в менеджере плагинов.

Обратите внимание: Этот плагин является коммерческим и требует отдельной покупки или подписки.

#2. Создание рабочего процесса Webhook

1. Перейдите на страницу Управление рабочими процессами.
2. Нажмите Создать рабочий процесс.
3. Выберите Триггер Webhook в качестве типа запуска.

4. Настройте параметры Webhook.

• Путь запроса: Пользовательский путь URL Webhook.
• Метод запроса: Выберите разрешенные методы HTTP (GET/POST/PUT/DELETE).
• Синхронный/Асинхронный: Выберите, следует ли ожидать завершения рабочего процесса перед возвратом результатов.
• Проверка: Настройте проверку подписи или другие механизмы безопасности.

#3. Настройка узлов рабочего процесса

Добавьте узлы рабочего процесса в соответствии с вашими бизнес-требованиями, например:

• Операции с коллекциями: Создание, обновление, удаление записей.
• Условная логика: Разветвление рабочего процесса на основе полученных данных.
• HTTP-запрос: Вызов других API.
• Уведомления: Отправка электронных писем, SMS и т.д.
• Пользовательский код: Выполнение кода JavaScript.

#4. Получение URL Webhook

После создания рабочего процесса система генерирует уникальный URL Webhook, обычно в следующем формате:

https://your-nocobase-domain.com/api/webhooks/your-workflow-key

#5. Настройка в сторонней системе

Настройте сгенерированный URL Webhook в сторонней системе:

• Установите адрес обратного вызова для отправки данных в системах форм.
• Настройте Webhook в GitHub/GitLab.
• Настройте адрес для отправки событий в WeCom/DingTalk.

#6. Тестирование Webhook

Протестируйте Webhook с помощью таких инструментов, как Postman или cURL:

curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"message":"Hello NocoBase"}}'

#Доступ к данным запроса

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

• {{$context.data}}: Данные тела запроса.
• {{$context.headers}}: Заголовки запроса.
• {{$context.query}}: Параметры запроса URL.
• {{$context.params}}: Параметры пути.

#Настройка ответа

#Синхронный режим

Возвращает результаты после завершения выполнения рабочего процесса. Можно настроить:

• Код состояния ответа: 200, 201 и т.д.
• Данные ответа: Пользовательский JSON-ответ.
• Заголовки ответа: Пользовательские HTTP-заголовки.

#Асинхронный режим

Немедленно возвращает подтверждение, а рабочий процесс выполняется в фоновом режиме. Подходит для:

• Длительных рабочих процессов.
• Сценариев, не требующих возврата результатов выполнения.
• Сценариев с высокой нагрузкой.

#Рекомендации по безопасности

#1. Включите проверку подписи

Большинство сторонних сервисов поддерживают механизмы подписи:

// Пример: Проверка подписи Webhook GitHub
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

#2. Используйте HTTPS

Убедитесь, что NocoBase развернут с использованием HTTPS для защиты передачи данных.

#3. Ограничьте источники запросов

Настройте белый список IP-адресов, чтобы разрешать запросы только из доверенных источников.

#4. Проверка данных

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

#5. Аудит журналов

Записывайте все запросы Webhook для отслеживания и устранения неполадок.

#Устранение неполадок

#Webhook не срабатывает?

1. Убедитесь, что URL Webhook указан правильно.
2. Проверьте, что статус рабочего процесса — "Включен".
3. Проверьте журналы отправки в сторонней системе.
4. Проверьте настройки брандмауэра и сети.

#Как отлаживать Webhook?

1. Просмотрите записи выполнения рабочего процесса для получения подробной информации о запросах и результатах.
2. Используйте инструменты для тестирования Webhook (например, Webhook.site) для проверки запросов.
3. Проверьте ключевые данные и сообщения об ошибках в записях выполнения.

#Как обрабатывать повторные попытки?

Некоторые сторонние сервисы повторяют отправку, если не получают успешного ответа:

• Убедитесь, что рабочий процесс является идемпотентным.
• Используйте уникальные идентификаторы для дедупликации.
• Записывайте идентификаторы обработанных запросов.

#Советы по оптимизации производительности

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

#Примеры сценариев

#Обработка отправки внешней формы

// 1. Проверка источника данных
// 2. Парсинг данных формы
const formData = context.data;

// 3. Создание записи клиента
// 4. Назначение ответственному лицу
// 5. Отправка подтверждающего письма отправителю
if (formData.email) {
  // Отправка уведомления по электронной почте
}

#Уведомление о push-событии GitHub

// 1. Парсинг данных push-события
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

// 2. Если это основная ветка
if (branch === 'main') {
  // 3. Запуск процесса развертывания
  // 4. Уведомление членов команды
}

#Связанные ресурсы

• Документация по плагину «Рабочий процесс»
• Рабочий процесс: Триггер Webhook
• Рабочий процесс: Узел HTTP-запроса
• Аутентификация с помощью ключей API