Отже, вас цікавить отримувати інформацію про зміну даних в Керуй на вашу сторону. Для цього людство придумало такий термін як "вебхук". По факту це HTTP POST запит, що буде надіслано на ваш URL, в момент коли потрібні вам дані в Керуй будуть створені/змінені/видалені.

Для отримання даних через вебхук (webhook) або, просто кажучи, HTTP запит на певну подію створення/зміни/видалення даних в Керуй відповідають автоматичні сценарії

Створення сценарію

Для створення сценарію на отримання вебхука слід перейти у Налаштування / Сценарії та натиснути кнопку Створити

У формі, що з'явиться слід вказати назву сценарії, контекст* виконання (сутність) та вибрати типи подій на які сценарій повинен реагувати

*наразі Керуй надає можливість створення сценаріїв тільки для документів. З часом ми додамо більше контекстів.

Після створення нового сценарії ви потрапите на сторінку редагування умов та кроків виконання

Умова

Для того, щоб задати умови за яких сценарій буде спрацьовувати слід натиснути на назву події

Після цього ви зможете додати необхідні вам умови спрацьовування сценарію (тригер) через форму

У цьому прикладі сценарій буде спрацьовувати для створення, оновлення або видалення документів типу Замовлення покупця де автором є учасник Тестер Петрович

Дія

Щоб додати дію надсилання HTTP запиту натискаємо на кнопку (+) та вибираємо пункт Дія

В меню дій натискаємо на "Надіслати HTTP запит"

У формі, що з'явиться ви можете вказати

• URL адресу куди буде надіслано HTTP запит

• HTTP метод - метод запиту (наразі доступний тільки POST)

• Серіалізатор - тип серіалізації даних

• HTTP заголовки - перелік заголовків котрі будуть частиною надісланого запиту

Усі зміни зберігаються автоматично і не вимагають підтвердження

Активація сценарію

Для того, що активувати сценарій слід натиснути на його статус бейдж біля назви у верхній частині редактора

Тільки активні сценарії будуть відпрацьовувати згідно з визначеними умовами та діями

Виконання

Для перевірки виконання можете спробувати "тригернути" необхідні умови. Для тестування радимо спробувати чудовий умовно безплатний сервіс https://webhook.site/

У цьому випадку на вказаний URL був надісланий POST HTTP запит з вказаними заголовками.

Наполегливо рекомендуємо використовувати Authortization заголовок для авторизації вхідних запитів, щоб запобігти сторонньому втручанню та витоку даних.

Журнал

Журнал усіх відправлених запитів ви можете знайти за адресою Налаштування / Сценарії / Виконання

Помилки при виконанні запиту

Якщо з певних причин вказаний URL не відповів, а статус відповіді відмінний від код 2хх то Керуй повторить спробу з певним інтервалом. Всього буде виконано максимум 10 спроб після чого виконання буде завершене з помилкою

Серіалізатор

Стандартний

За замовчуванням Керуй пропонує використовувати стандартний серіалізатор даних, що використає знайомі вам по API query такі як getDocument та інші залежно від контексту виконання. Ви можете вплинути на формат отримання даних у запиті через зміну типу серіалізатора.

Змінений

Дозволяє вам вказати тільки потрібні поля

В такому випадку при формуванні блоку data запит getDocument поверне обмежену кількість полів

Власний

Дає вам повний контроль над тілом запиту, але вимагає написання `JSON` серіалазтор з використанням шаблонізатора mustache

Метадані

Для стандартного та зміненого серіалізатора Керуй завжди буде обгортати блок data поточними метаданими, щоб вам було простіше зрозуміти контекст виконання

{
    "company_id": "d81bfb3b-8e23-4146-ae68-be533d807dbb",
    "context": "documents",
    "data": {...},
    "event": "updated",
    "run_id": "ca23daba-ac09-4009-a732-d7bdb2c75d01",
    "run_number": 78,
    "workflow_id": "fb48ab5c-7154-42f9-902a-f8ce7d01d2e2"
}

• company_id - ідентифікатор компанії

• context - сутність виконання

• event - тип події (created/updated/deleted)

• run_id - ідентифікатор виконання

• run_number - порядковий номен виконання

• workflow_id - ідентифікатор сценарію

Змінні

Для зручного перевикористання змінних та секретних ключів радимо використовувати розділ змінні.

Щоб додати змінну слід перейти Налаштування / Сценарії / Змінні та натиснути на кнопку Додати

• Ключ - ідентифікатор змінної. Можна використовувати тільки великі символи A-Z та _

• Значення - безпосереднє значення змінної котре буде використане під час серіалізації

• Таємниця - для дуже важливих і таємних значень. В такому випадку ці значення будуть зберігатись в Керуй у закодованому вигляді і ніхто більше не зможе їх прочитати

• Нотатки - для того, щоб не забути для чого вам ця змінна

Після збереження усі змінні будуть доступні в загальній таблиці, але таємні будуть майже повністю приховані (крім перших 3-х символів)

Використати значення змінної ви можете за допомогою шаблонізатора mustache де в середині {{..}} просто вказати ключ змінної

Під час серіалізації запиту ключ змінної буде замінено на значення. Таким чином ви можете один раз визначити свої змінні та перевикористовувати у всіх сценаріях.

Успішних обмінів даними!