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

Блок сценария 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.

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

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

После этого вы можете протестировать запрос. Нажмите на кнопку “Отправить тест” и выберите подходящий контакт, на котором проверите работоспособность вебхука.

В открывшемся окне вы можете найти контакт через поиск:

Также можно найти контакт через сегмент. Для этого выберите вариант “Просмотр контактов из выбранной группы”.

Чтобы просмотреть карточку контакта, нажмите на иконку глаза, а чтобы выбор контакта применился, кликните по подсвеченной строке с контактом из списка и нажмите “Далее”, затем “Отправить заявку”.

В этом же окне вы получите ответ с 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.

Затем введите идентификационные данные (логин и пароль/токен/ключ) и нажмите кнопку “Готово”.

5. В теле POST-запроса вы можете отправить произвольное количество данных. Для этого активируйте соответствующий свитчер, из выпадающего списка выберите формат вводимых данных и впишите их ниже. Доступные форматы: JSON, XML, Text. К параметрам из события нужно обращаться с помощью apache velocity, пример:
   "param": "$data.get('param')"  

6. Проверьте корректность настроек через тестирование вебхука. В окне настроек нажмите на кнопку “Отправить тест”.

Система предложит откуда взять данные для тестирования: из карточки контакта или из события. Если в URL вебхука настроено обращение к параметру из события, то при тестировании система предложит выбрать событие из списка тех, которые приходили когда-либо в систему, либо вписать тело события вручную.

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

Вы можете выбрать другой контакт ① либо просмотреть выбранный ②.

После того как нажмете “Далее” и “Отправить заявку”, вы получите ответ с Headers и Body запроса:

Чтобы отобразить полученный промокод в сообщении, впишите в текстовую область выражение такого вида:

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

где WH5 – название источника (название вебхука),
promocode – название переменной, которая содержит значение промокода.

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

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

В настройках блока Webhooks нажмите “Управление webhooks”. Вы попадете в раздел со списком вебхуков, где сможете:

• создать новый вебхук,
• редактировать любой существующий,
• протестировать вебхук,
• удалить ненужный,
• посмотреть список удаленных.

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