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

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

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

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

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

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

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

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

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

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

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

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

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

1. Введіть назву вебхука, використовуючи будь-які символи (обов'язкове поле), та опис (необов'язкове поле).

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

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

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

5. У вікні “Створити конектор” введіть такі дані:

• Назву нового конектора.

• Потрібний тип автентифікації. Доступно три типи:  Basic, Bearer token та API key.

• Впишіть логін та пароль/токен/ключ.

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

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

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

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

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

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

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

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

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

Ви можете відобразити отриману інформацію у повідомленні, прописавши вираз через мову Velocity. 

Перейдіть до розділу “Повідомлення” → “Повідомлення” → “Новий Email”.

У будь-яку текстову область зі значенням отриманої змінної вставте вираз для виведення динамічних даних.

Приклад: $!mathTool.toInteger($data.contacts_get_by_email.get(0).id),

де contacts_get_by_email – назва нашого вебхука (тут він відіграє роль джерела даних),

get(0).id – звернення до змінної у джерелі, що вказує на потрібний нам параметр. У нашому випадку це ID контакту.

Під час тестування в повідомлення підставиться ID контакту, який був знайдений за email з події за допомогою вебхука:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Управління вебхуками

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

• створити новий вебхук,

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

• протестувати вебхук,

• видалити непотрібний,

• переглянути список видалених.

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