Вебхуки (Webhooks)

Webhooks (рус. вебхуки) – это пользовательские обратные запросы по HTTP. Обычно их отработка связана с каким-либо событием, например, прочтением письма или запуском приветственной серии. Вебхуки считаются удобным инструментом для отслеживания событий в реальном времени: как только событие наступает, на внешний URL отправляется запрос.

В eSputnik есть два варианта для настройки и использования вебхуков:

1. Добавление внешнего URL для аккаунта, чтобы отслеживать активности пользователей.
2. Настройка кастомных запросов в сценариях через специальный блок Webhook.

Вебхуки для отслеживания активностей

Эта функциональность позволяет в режиме реального времени получать информацию обо всех активностях контактов. Данные будут поступать регулярно на указанный URL POST запросами, как описано ниже.

Для сравнения/альтернативы есть метод API v2/contacts/activity. Он работает при отправке с вашей стороны GET запросов, в которых можно указывать интервал времени (не более 3 месяцев) и параметры (email, статус и т. д.).

При помощи вебхуков вы будете получать информацию обо всех активностях пользователя после отправленных в любом канале сообщений:

  • доставлено;
  • ошибка доставки;
  • прочитано;
  • получатель перешел по ссылке;
  • получатель отписался от рассылок;
  • получатель пожаловался на спам.

Как подключить вебхуки для аккаунта

Сконфигурируйте на своем сервере URL, на который вы хотите получать уведомления, POST запросы в формате JSON.

Затем этот URL внесите в настройки eSputnik. Для этого авторизуйтесь в системе, зайдите в настройки аккаунта → раздел “Лаборатория”. Активируйте опцию “Вебхуки” и вставьте ваш URL в поле “Webhook-адрес”.

Как активировать функцию “Вебхуки”

После произойдет проверка URL-адреса GET запросом. Если будет отображена ошибка, то, возможно, на вашей стороне сработала блокировка нашего запроса. Узнать точную причину можно по коду ошибки сервера. Система проверит доступность URL-адреса. Если все прошло успешно, то настройка завершена.

После этого произведите любое действие в аккаунте. Например, отправьте себе письмо. В течение нескольких минут на указанный адрес будет отправлен POST запрос с информацией по последним активностям.

POST запросы отправляются в формате JSON при появлении активности пользователей (отправка email, открытие сообщения, переход и т. д.).
Если webhook URL не возвращает код ответа HTTP 200, то попытка POST запроса будет повторяться с увеличивающимися интервалами (1 минута, 2 минуты, 4 минуты, 8 минут – до одного запроса в час). Следующие запросы будут отложены до успешной отправки первого, а затем будут отправляться так же последовательно.

Перечень возможных параметров 

Параметр Тип Описание
broadcastId int Идентификатор рассылки
workflowId int Идентификатор сценария
workflowBlockId string Служебный параметр сценария
sourceEventKey string Ключ типа события
sourceEventTypeKey string Значение ключа события
iid string Служебный параметр
contactId int Идентификатор контакта
email string Email контакта
sms string Номер телефона контакта
viber string Номер телефона контакта
mobilepush string Token подписчика мобильного приложения
webpush string Token подписчика вебпуш-уведомлений
activityStatus string DELIVERED – сообщение доставлено
UNDELIVERED – сообщение не доставлено (в параметре statusDescription описывается причина)
READ – сообщение прочитано
UNSUBSCRIBED – контакт отписался от рассылок
CLICKED – контакт переходил по ссылкам в сообщении
SPAM – контакт пожаловался на спам
SUBSCRIPTION_CHANGED – контакт изменил категорию подписки
messageId int Идентификатор сообщения
messageInstanceId int Идентификатор экземпляра сообщения
messageTag string Метка сообщения
activityDateTime string Дата и время, когда случилась активность
statusDescription string Это поле возвращается только в случае, если статус – UNDELIVERED. Содержит причину, по которой сообщение не было доставлено. Это может быть ответ сервера получателя, ответ системы о невозможности отправить сообщение, etc.
viewMessageLink string Содержит ссылку на веб-версию сообщения
clickEventLink string Содержит ссылку, по которой перешел контакт (при статусе CLICKED)
hardBounce bool Это поле возвращается только в случае, если статус – UNDELIVERED. Параметр оповещает о наличии контакта в черном списке.
false – не в черном списке на момент отправки сообщения
true – в черном списке на момент отправки
statusData   Массив с данными
subscripton   Массив с данными
subscriptons array of string Ключи категорий подписок

Тестовый пример вебхука в виде массива JSON со всеми возможными вариантами статусов:

[
  {
    "iid": "ffd3e1a7-a270-4e58-94de-5ac681c5c8e7",
    "contactId": 687266822,
    "activityStatus": "SUBSCRIPTION_CHANGED",
    "mediaType": email,
    "activityDateTime": "2019-09-26T14:45:18",
    "statusData": {
      "subscription": {
        "subscriptions": [
          "SMARTPHONES",
          "TABLETS",
          "LAPTOPS"
        ]
      }
    }
  },
  {
    "broadcastId": 2833914,
    "iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
    "contactId": 295953704,
    "email": "test@rambler.ru",
    "activityStatus": "DELIVERED",
    "mediaType": email,
    "messageId": 976440,
    "messageInstanceId": 1344540,
    "activityDateTime": "2018-03-01T13:31:52",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "broadcastId": 2833915,
    "hardBounce": false,
    "iid": "D5AF8EFC-2E8F-4BB5-B427-77D554B30E65",
    "contactId": 357885291,
    "sms": "380671234567",
    "activityStatus": "UNDELIVERED",
    "mediaType": sms,
    "activityDateTime": "2019-10-01T03:43:49",
    "statusDescription": "IM_NO_MONEY"
  },
  {
    "broadcastId": 2833914,
    "hardBounce": false,
    "iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
    "contactId": 295953704,
    "email": "test@rambler.ru",
    "activityStatus": "UNDELIVERED",
    "mediaType": email,
    "messageId": 976440,
    "messageInstanceId": 1344540,
    "activityDateTime": "2018-03-01T13:31:58",
    "statusDescription": "smtp;554 5.7.1 Spam message rejected; If this is not spam contact abuse",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
    "contactId": 1258810400,
    "email": "test@gmail.com",
    "activityStatus": "READ",
    "mediaType": email,
    "messageId": 1235215,
    "messageInstanceId": 1622691,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T04:05:53",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
    "contactId": 1258810400,
    "email": "test@gmail.com",
    "activityStatus": "UNSUBSCRIBED",
    "mediaType": email,
    "messageId": 1166457,
    "messageInstanceId": 1550164,
    "messageTag": "1521722870",
    "activityDateTime": "2018-05-15T09:56:40",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
    "contactId": 1258810400,
    "email": "test@gmail.com",
    "activityStatus": "CLICKED",
    "mediaType": email,
    "messageId": 1242672,
    "messageInstanceId": 1630305,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T04:45:04",
    "viewMessageLink": "https://123.esclick.me/test",
    "clickEventLink": "https://test.ua/promo/"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
    "contactId": 1258810400,
    "email": "test@mail.ru",
    "activityStatus": "SPAM",
    "mediaType": email,
    "messageId": 1242672,
    "messageInstanceId": 1630305,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T08:23:56",
    "viewMessageLink": "https://123.esclick.me/test"
  }
]

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

Блок сценария Webhook позволяет работать с параметрами из событий и из карточки контакта в eSputnik.

Блок сценария Webhook

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

  1. Обратиться к собственному ресурсу, который обработает запрос и вернет в сообщение данные для персонализации (например, личный промокод или токен для авторизации).
  2. Отдать на внешний ресурс данные из события или из карточки контакта (например, id заказа, допполе “id контакта в мессенджере” или “День рождения”).

Важно

Передать через webhook можно только данные контакта (поля + дополнительные поля) и параметры из события, которое запустило сценарий с вебхуком.

Передача данных в вебхуках в большинстве случаев настраивается в формате JSON, но также доступны форматы XML и Text.

Как создать webhook в сценарии

  1. Перейдите в раздел “Триггеры” → “Сценарии” и нажмите “Новый сценарий”.
  1. На панели слева откройте вкладку “Действия” и выберите блок Webhook:

Где найти блок Webhook

  1. Справа на панели настроек этого блока нажмите кнопку “Создать webhook”:

Создание вебхука из блока сценария

  1. Откроется окно настройки вебхука.

Выбор типа запроса вебхука

Тут вы увидите, что можно выбрать тип запроса: GET или POST.

Работа с GET запросом

Используйте этот тип, когда нужно через ссылку запросить данные на стороннем источнике для использования в сценарии и подстановки в сообщение внутри этого сценария. Данные передаются в URL в виде пар "имя – значение". Что нужно для настройки вебхука:

Создание вебхука с типом GET

  1. Задайте название вебхука, используя любые символы (обязательное поле), и описание (необязательное поле).

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

  3. Если ваш ресурс считывает параметры из заголовков, активируйте этот переключатель и впишите туда соответствие переменных и значений, к которым будете обращаться:

Передавать параметры в заголовках

  1. Выберите коннектор для авторизации. Если нужно настроить новый, выберите из выпадающего списка вариант “Новый коннектор”.

Новый коннектор

Откроется окно “Создать коннектор”. В открывшемся окне введите необходимые данные:

Данные для создания новой авторизации

  1. Задайте название нового коннектора.
  2. Выберите нужный тип аутентификации.

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

  • Basic,
  • Bearer token,
  • API key.
  1. Впишите логин и пароль/токен/ключ.

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

Новый коннектор создан и применен в вебхуке

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

Выберите контакт для теста

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

Поиск контакта для теста

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

Выбрать контакт из группы

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

Отправка тестового запроса

В этом же окне вы получите ответ:

Результат теста GET запроса

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

Сохранение настроек нового вебхука

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

Блок с настроенным вебхуком в сценарии

Обратите внимание, что в настройках блока 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”.

Создание вебхука POST

  1. В окне создания или редактирования вебхука дайте ему название и выберите тип POST. Впишите URL ресурса, используя защищенный протокол HTTPS. В этой ссылке вы можете использовать переменные, обращаясь к параметрам события или полям контакта. В примере мы обращаемся к TOWN – это стандартное поле контакта в eSputnik.

Настройте адрес для передачи данных

  1. Если ваше приложение считывает параметры из заголовков, активируйте соответствующий свитчер, укажите нужные параметры и их значения.

Укажите параметры и значения

  1. Чтобы настроить аутентификацию, активируйте одноименный свитчер. Выберите существующий набор для авторизации либо создайте новый коннектор.

Выберите набор данных для аутентификации

Чтобы создать новый набор для аутентификации, в выпадающем списке выберите вариант “Новый коннектор”.

Создание авторизации

В открывшемся окне задайте название нового коннектора, выберите нужный тип аутентификации. Доступно три типа:

  • Basic,
  • Bearer token,
  • API key.

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

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

Впишите данные в тело запроса

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

Отправка теста POST запроса

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

Впишите тело события вручную

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

Тестирование на контактах

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

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

Результат тестирования POST запроса

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

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

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

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

Результат подстановки промокода из вебхука

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

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

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

  • создать новый вебхук,
  • редактировать любой существующий,
  • протестировать вебхук,
  • удалить ненужный,
  • посмотреть список удаленных.
Остались вопросы?
Специалисты обязательно ответят и помогут решить вашу проблему!
Обратный звонок
Оставьте заявку – и наш специалист свяжется с вами в рабочее время.
Отправить заявку
Консультация в чате
Готовы к вашим вопросам!
Написать в чат
Электронная почта
Напишите в службу поддержки eSputnik.
Отправить email