Вебхуки в сценаріях

Блок сценарію Webhook дозволяє працювати з даними контексту сценарію.

Цей запит вивантажує та надсилає дані контакту з eSputnik в інші системи та, навпаки, отримує дані із зовнішніх систем.

З його допомогою в рамках сценарію ви можете:

1. Звернутися до власного ресурсу, який обробить запит і поверне дані для:

• персоналізації (наприклад, особистий промокод або токен для авторизації) у повідомленні;
• перевірки параметрів відповіді.

2. Віддати на зовнішній ресурс дані з події або картки контакту (наприклад, ID замовлення, додаткове поле ID контакту в месенджері або день народження).

Використання відповідей вебхуків у повідомленнях та сценаріях

Ви можете легко інтегрувати JSON-відповіді, отримані від зовнішніх сервісів через вебхуки, безпосередньо у сценарії. Це дає змогу повною мірою застосовувати дані (наприклад, із CRM) в реальному часі для персоналізації комунікацій і прийняття обґрунтованих рішень у логіці сценарію.

Ключові переваги:

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

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

Як це працює

Коли вебхук повертає відповідь у форматі JSON, дані зберігаються в сценарії у вигляді об’єкта з назвою, яка відповідає назві джерела даних (тобто назві вебхука). Ви можете звертатися до цих даних:

• У повідомленнях — за допомогою синтаксису Velocity
• У наступних блоках Змінна відповідає регулярному виразу та Webhook в сценарії — через регулярні вирази

Приклад: використання відповіді вебхука в повідомленнях

Припустімо, ви надсилаєте запит до джерела даних crmWebhook, щоб отримати персональний промокод. Відповідь виглядає так:

{  
  "externalId": "user_12345",  
  "promoCode": "WELCOME-5OFF"  
}

Щоб відобразити промокод у повідомленні в межах сценарію, використайте такий синтаксис Velocity:

• $!crmWebhook.promoCode

Ця коротка форма найзручніша для використання прямо в тексті повідомлення. Довша форма нижче повертає те саме значення і корисна, коли назва джерела даних зберігається у змінній або має формуватися динамічно:

• $!data.get("crmWebhook").get("promoCode")

Де:

• crmWebhook — назва вашого джерела даних (вебхука)
• promoCode — поле з відповіді, значення якого потрібно відобразити

У результаті кожен контакт отримає свій унікальний промокод, отриманий із зовнішньої системи.

Приклад: використання відповіді вебхука в блоці Умова

Припустимо, ви хочете перевірити, чи є контакт учасником програми лояльності. Ви надсилаєте запит до crmWebhook, і сервіс відповідає:

{  
  "externalId": "user_98765",  
  "isLoyaltyMember": true  
}

Щоб налаштувати блок Змінна відповідає регулярному виразу:

• У полі Назва введіть назву джерела даних: crmWebhook
• У полі Патерн введіть регулярний вираз для перевірки значення, наприклад:
  .*true.*.

• Якщо значення isLoyaltyMember дорівнює true, контакт іде по гілці Так.
• Інакше — по гілці Ні.

Ці приклади демонструють лише кілька способів інтеграції зовнішніх даних у сценарії. Ви можете розширити цей підхід, наприклад:

• Перевіркою наявності конкретних значень або вкладених полів
• Застосуванням кількох регулярних виразів
• Комбінуванням логіки Velocity для динамічного відображення контенту

Використовуйте відповіді вебхуків, щоб створювати розумніші автоматизації та масштабувати персоналізацію в реальному часі.

Створення вебхука в сценарії

1. Перейдіть у розділ Тригери → Сценарії та натисніть Новий сценарій.

2. На панелі зліва відкрийте вкладку Дія та виберіть блок Webhook.

3. Праворуч на панелі налаштувань цього блоку натисніть кнопку Виберіть webhook:

4. Виберіть вже створений вебхук або натисніть + Новий webhook.

5. У вікні налаштування нового вебхука введіть назву, опис (опційно) та виберіть з випадного меню тип запиту: GET чи POST.

Підстановка даних контексту сценарію

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

Робота з GET-запитом 

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

Налаштування вебхука:

1. Введіть назву вебхука, використовуючи будь-які символи (обов'язкове поле), та опис (необов'язкове поле).
2. Впишіть URL ресурсу через захищений протокол HTTPS (якщо ввести HTTP, система не дозволить зберегти посилання). Після знаку питання пропишіть змінні, які бажаєте повернути. У прикладі ми хочемо передати значення параметра email з події, яка запускає сценарій, та звертаємось до поля EMAIL, яке відноситься до картки контакту на ресурсі, куди ми надсилаємо GET-запит.
3. Якщо ваш ресурс може обробляти параметри заголовків, активуйте цей перемикач і впишіть туди назви параметрів та їх значення, до яких звертатиметеся.

Нижче наведені приклади запису параметрів та їх значень, які можуть використовуватись:

Наприклад, URL з усіма наведеними вище параметрами виглядатиме так:

https://api.example.com/endpoint?phone=$phone&email=$email&name=$name&city=$city&contactID=$contact_ID&param=$workflowInstanceId

4. Виберіть конектор для авторизації. Якщо потрібно налаштувати новий, виберіть зі спадного меню варіант Новий конектор.
5. У вікні Створити конектор введіть такі дані:

• Назву нового конектора.
• Потрібний тип автентифікації. Доступно чотири типи:  Basic, Bearer token, API key та OAuth 2.0.
• Впишіть логін та пароль/токен/ключ.

Для типу OAuth 2.0 у формі конектора також є поле Провайдер. Якщо вибрано Інший провайдер, з'являється поле Grant type, яке визначає спосіб авторизації:

• Authorization code — стандартний флоу з входом на боці провайдера: після натискання Підключити відбувається переадресація на сторінку авторизації провайдера (використовується поле URL аутентифікації).
• Client credentials — без входу користувача: токен доступу запитується безпосередньо з Token URL за допомогою Client ID, Client Secret і Scopes, указаних у розділі Розширена конфігурація. Цей тип підходить для інтеграцій сервер–сервер, наприклад із Microsoft Entra ID.

Отриманий токен автоматично додається до заголовка Authorization: Bearer запитів і оновлюється незадовго до завершення строку дії.

Після цього натисніть Готово, і новий конектор автоматично застосується у вебхуку, що створюється.

Тестування GET-запиту

1. Натисніть кнопку Відправити тест.

2. Вкажіть, звідки брати дані для тестового запиту і натисніть Далі. Введіть дані як об'єкт JSON, дотримуючись того самого регістру символів, що й у змінних вебхука, наприклад:

{
  "EMAIL": "[email protected]"
}

3. Натисніть Відправити запит.

У вікні тестування ви отримаєте відповідь запиту:

Натисніть по стрілці Назад у лівому верхньому куті діалогового вікна та закінчіть створення вебхука, натиснувши кнопку Готово.

Тепер новий вебхук доступний у списку для вибору в сценарії:

Робота з POST-запитом

Розглянемо, як надіслати дані контакту до зовнішнього сервісу за допомогою POST-запиту. У цьому прикладі ми використовуємо Postman Echo — сервіс, який повертає надіслані дані запиту, щоб протестувати вебхук.

Щоб налаштувати вебхук із POST-запитом, виконайте такі дії:

1. У налаштуваннях блоку Webhook натисніть кнопку Виберіть webhook:

2. У вікні налаштування вебхука вкажіть назву post_city, виберіть тип запиту POST і впишіть таку URL-адресу:

https://postman-echo.com/post

3. Якщо ваша програма зчитує параметри із заголовків, активуйте відповідний перемикач, вкажіть потрібні параметри та їхні значення. Для Postman Echo додаткові заголовки в цьому прикладі не потрібні.

4. Щоб налаштувати аутентифікацію, активуйте однойменний перемикач. Виберіть існуючий набір для авторизації або створіть новий конектор. Для Postman Echo автентифікацію можна залишити вимкненою.

5. Увімкніть Передавати JSON у тілі запиту і введіть:

{
  "city": "$CITY",
  "email": "$EMAIL"
}

Доступні формати: JSON, XML, Text.

До параметрів з події слід звертатися за допомогою Apache Velocity, наприклад: "param": "$param".

Тестування POST-запиту

1. У вікні налаштувань натисніть кнопку Відправити тест.

2. Введіть дані тестової події. Використовуйте той самий регістр літер, що й у змінних вебхука:

{
  "CITY": "Kyiv",
  "EMAIL": "[email protected]"
}

3. Натисніть Далі, перевірте підставлені значення та натисніть Відправити запит. Відповідь містить надіслані значення в об’єкті json:

Щоб підставити отримане значення міста у повідомлення, використайте один із рівнозначних варіантів: $data.get('post_city').get('json').get('city') / $post_city.get('json').get('city').

Де:

• post_city – назва вебхука;
• json – об'єкт, який повертає Postman Echo;
• city – поле з потрібним значенням.

Другий варіант коротший і працює так само — обирайте той, який зручніше читається у вашому повідомленні.

Очікування результату вебхука

Після надсилання вебхука сценарій призупиняється, доки обробник не повідомить остаточний результат. Сценарій не надсилає повторні запити для перевірки проміжного статусу. Коли надходить сповіщення про результат, eSputnik зберігає відповідь або помилку й продовжує сценарій. Резервний тайм-аут не дозволяє сценарію очікувати нескінченно, а дубльовані сповіщення не запускають наступний блок повторно.

Цей механізм очікування не змінює обробку невдалих запитів: для серверних помилок і тайм-аутів діють наведені нижче правила повторних спроб.

Правила повторних спроб

Якщо endpoint повертає серверну помилку 5xx, eSputnik повторює запит кожні 3 хвилини — до 3 повторних спроб. Відповіді інших класів не запускають ці автоматичні повтори.

Зробіть endpoint ідемпотентним, щоб повторне опрацювання того самого запиту не створювало дубльованих операцій.

Розширені параметри блоку

Блок має розширені параметри, випадки заповнення яких детально розглянуто в окремій статті. 

Керування webhooks

У налаштуваннях блока Webhook натисніть Керування webhooks. Ви потрапите до розділу зі списком вебхуків, де зможете:

• створити новий вебхук,
• редагувати будь-який існуючий,
• протестувати вебхук,
• видалити непотрібний,
• переглянути список видалених.

В історії запусків сценарію з вебхуком ви побачите деталі блоку: