Вебхуки (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 минут – до одного запроса в час). Следующие запросы будут отложены до успешной отправки первого, а затем будут отправляться так же последовательно.

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

Тестовый пример вебхука в виде массива 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.

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

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

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

Как создать 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. Впишите логин и пароль/токен/ключ.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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