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

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

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

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

📘

Важливо

Надіслати через вебхук можна лише дані контакту (поля + додаткові поля) та параметри з події, яка запустила сценарій із вебхуком. Передача даних у вебхуках переважно налаштовується у форматі JSON, але також доступні формати XML та Text.

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

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

2. На панелі зліва відкрийте вкладку “Інше” та виберіть блок “Webhook”.

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

4. У вікні налаштування вебхука виберіть з випадного меню тип запиту: GET чи POST.

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

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

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

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

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

📘

Примітка

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

❗️

Важливо

Для $workflowInstanceId регістр символів має значення, а для полів контакту — ні.

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

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

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

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

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

2. Виберіть відповідний контакт зі списку або знайдіть через пошук і натисніть “Далі”.

Для пошуку контактів через групи виберіть “Перегляд контактів обраної групи”.

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

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

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

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

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

Розглянемо на прикладі, коли потрібно надіслати дані про місто контакту, щоб отримати для нього промокод із зовнішнього джерела.

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

1. У налаштуваннях блоку Webhook натисніть кнопку “Створити вебхук”.

2. У вікні створення або редагування вебхука дайте йому назву та виберіть тип POST. Впишіть URL-адресу за допомогою захищеного протоколу HTTPS. У цьому посиланні можна використовувати змінні, звертаючись до параметрів події або полів контакту. У прикладі ми звертаємося до TOWN – це стандартне поле контакту в eSputnik.

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

📘

Примітка

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

❗️

Важливо

Для $workflowInstanceId регістр символів має значення, а для полів контакту — ні.

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

5. Щоб створити новий набір для автентифікації, у списку виберіть варіант “Новий конектор”.

У вікні задайте назву нового конектора, виберіть потрібний тип аутентифікації. Потім введіть ідентифікаційні дані (логін та пароль/токен/ключ) та натисніть кнопку “Готово”.

У POST-запиті дозволено надсилати довільну кількість даних. Для цього активуйте відповідний перемикач, виберіть формат даних зі списку та впишіть їх нижче. Доступні формати: JSON, XML, Text.

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

📘

Примітка

У тілі запиту можна передавати значення $workflowInstanceId.

Відображення значення $workflowInstanceId в параметрах події:

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

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

2. Система запропонує, звідки взяти дані для тестування: з контактної картки або з події. Якщо в URL вебхука налаштовано звернення до параметра з події, під час тестування система запропонує вибрати подію зі списку тих, які приходили будь-коли у систему, або вписати тіло події вручну.

Оскільки в нашому прикладі вказано звернення до поля контакту, для тесту необхідно вибрати контакт з бази в акаунті eSputnik.

Ви можете вибрати інший контакт (1) або переглянути обраний (2).

Після того як натиснете “Далі” та “Відправити запит”, ви отримаєте відповідь з Headers та Body запиту:

Щоб відобразити отриманий промокод у повідомленні, впишіть у текстову область вираз такого вигляду: $data.get('WH5').get('promocode').

Де:

• WH5 – назва джерела (назва вебхука);
• promocode – назва змінної, що містить значення промокоду.

Результат підстановки отриманого промокоду в лист:

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

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

Управління webhooks

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

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

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