#Интеграция рабочего процесса через вебхук

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

#Обзор

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

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

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

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

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

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

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

Когда данные меняются во внешних системах (например, CRM, ERP), вебхуки могут отправлять обновления в NocoBase в реальном времени, чтобы поддерживать синхронизацию.

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

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

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

#Гибкий механизм триггера

• Поддержка HTTP-методов GET, POST, PUT, DELETE
• Автоматический разбор JSON, form data и других распространённых форматов
• Настраиваемая проверка запроса для допуска только доверенных источников

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

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

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

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

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

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

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

Note: Это коммерческий плагин. Подробные инструкции по активации см.: в руководстве

#2. Создать рабочий процесс с вебхуком

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

4. Настройте параметры вебхука

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

#3. Настроить узлы рабочего процесса

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

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

#4. Получить URL вебхука

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

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

#5. Настроить стороннюю систему

Укажите сгенерированный URL вебхука в сторонней системе:

• задайте callback-адрес отправки данных в системах форм
• настройте вебхук в GitHub/GitLab
• настройте адрес push-событий в WeCom/DingTalk

#6. Протестировать вебхук

Проверьте вебхук инструментами вроде 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"}}'

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

В рабочем процессе доступ к данным вебхука осуществляется через переменные:

• {{$context.data}}: тело запроса
• {{$context.headers}}: заголовки запроса
• {{$context.query}}: query-параметры URL
• {{$context.params}}: path-параметры

#Конфигурация ответа

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

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

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

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

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

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

#Лучшие практики безопасности

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

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

// Пример: проверка подписи 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. Логирование аудита

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

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

#Вебхук не срабатывает?

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

#Как отлаживать вебхуки?

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

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

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

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

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

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

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

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

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

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

#Уведомление о пуше в GitHub

// 1. Разобрать данные push
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

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

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

• Документация плагина рабочих процессов
• Рабочий процесс: триггер вебхук
• Рабочий процесс: узел HTTP-запроса
• Аутентификация по API-ключам