#Інтеграція Webhook у робочих процесах

Завдяки тригерам Webhook, NocoBase може отримувати HTTP-виклики від сторонніх систем та автоматично запускати робочі процеси, забезпечуючи безперебійну інтеграцію із зовнішніми системами.

#Огляд

Webhook — це механізм "зворотного API", який дозволяє зовнішнім системам активно надсилати дані до NocoBase, коли відбуваються певні події. Порівняно з активним опитуванням, 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. Увімкніть перевірку підпису

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

// Приклад: Перевірка підпису GitHub Webhook
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. Перевірте ключові дані та повідомлення про помилки в записах виконання.

#Як обробляти повторні спроби?

Деякі сторонні сервіси повторно надсилають запити, якщо не отримують успішної відповіді:

• Переконайтеся, що робочий процес є ідемпотентним.
• Використовуйте унікальні ідентифікатори для дедуплікації.
• Записуйте ID оброблених запитів.

#Поради щодо оптимізації продуктивності

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

#Приклади сценаріїв

#Обробка надсилання зовнішньої форми

// 1. Перевірте джерело даних
// 2. Розберіть дані форми
const formData = context.data;

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

#Сповіщення про надсилання коду GitHub

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

// 2. Якщо це основна гілка
if (branch === 'main') {
  // 3. Запустіть процес розгортання
  // 4. Сповістіть членів команди
}

#Пов'язані ресурси

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