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

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

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

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

Як створити webhook у сценарії

1. Перейдіть у розділ “Тригери” → “Сценарії” та натисніть “Новий сценарій”.
2. На панелі зліва відкрийте вкладку “Дії” та виберіть блок Webhook:
   
3. Праворуч на панелі налаштувань цього блоку натисніть кнопку "Створити webhook":
   
4. Відкриється вікно налаштування вебхука.

Тут ви побачите, що можна вибрати тип запиту: GET чи POST.

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

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

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

Відкриється вікно "Створити конектор". У вікні введіть необхідні дані:

1. Вкажіть назву нового конектора.
2. Виберіть потрібний тип автентифікації.

Доступно три типи автентифікації:

• Basic,
• Bearer token,
• API key.

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

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

Після цього ви можете протестувати запит. Натисніть на кнопку "Надіслати тест" і виберіть відповідний контакт, на якому перевірите працездатність вебхука.

У вікні ви можете знайти контакт через пошук:

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

Щоб переглянути картку контакта, натисніть на іконку ока, а щоб вибрати контакт, клацніть по підсвіченому рядку з контактом зі списку і натисніть “Далі”, потім “Відправити заявку”.

У цьому вікні ви отримаєте відповідь з Headers та Body запиту:

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

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

Зверніть увагу, що в налаштуваннях блоку Webhook є три поля для ідентифікації контакту за параметром з події: “ID контакту”, “Телефон” та “Email контакту”. Достатньо вписати один із цих трьох параметрів, щоб сценарій визначив, дані якого контакту потрібно отримати/передати у вебхуку. У прикладі сценарій запускає подію зі змінною email. Тому для поля "Email контакту" у блоці Webhook потрібно вписати ${email}.

Тепер ви можете відобразити отриману інформацію у повідомленні, прописавши вираз через мову Velocity. Перейдіть до розділу “Повідомлення” → “Створити Email” або виберіть свій шаблон.

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

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

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

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

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

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

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

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

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

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

У вікні задайте назву нового конектора, виберіть потрібний тип аутентифікації. Доступно три типи:

• Basic,
• Bearer token,
• API key.

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

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

"param": "$data.get('param')"

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

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

Ви можете вибрати інший контакт ① або переглянути обраний ②.

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

$data.get('WH5').get('promocode'), 

де WH5 – назва джерела (назва вебхука),

promocode – назва змінної, що містить значення промокоду.

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

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

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

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

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