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

Блок сценария 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. Нажмите “Отправить запрос”.

В окне тестирования вы получите ответ запроса:

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

Теперь новый вебхук доступен в списке для выбора в сценарии.

Обратите внимание, что в настройках блока “Webhook” есть три поля для идентификации контакта по параметру из события: “Contact ID”, “Номер телефона” и “Email”. Достаточно вписать один из этих трех параметров, чтобы сценарий определил, данные какого контакта нужно получить/передать в вебхуке. В нашем примере сценарий запускает событие с переменной email. Поэтому для поля “Email” в блоке “Webhook” нужно вписать {emailAddress}.

Теперь вы можете отобразить полученную информацию в сообщении, прописав выражение через язык 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” нажмите “Управление вебхуком”. Вы попадете в раздел со списком вебхуков, где сможете:

• создать новый вебхук,

• редактировать любой существующий,

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

• удалить ненужный,

• посмотреть список удаленных.

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