Webhooks

Общее описание

Webhooks (рус. - вебхуки) - метод отслеживания в реальном времени определенных событий в системе eSputnik и оповещения сторонних URL о них.

События, которые вы будете получать

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

  • доставлено;

  • ошибка доставки;

  • прочитано;

  • получатель перешел по ссылке;

  • получатель отписался от рассылок;

  • получатель пожаловался на спам.

Как внедрить вебхуки?

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

Контроль триггеров в eSputnik

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

Система проверит доступность URL-адреса. Если все прошло успешно, то настройка завершена.

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

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

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

[{
"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
"contactId": 295953704,
"email": "test@rambler.ru",
"activityStatus": "DELIVERED",
"messageId": 976440,
"messageInstanceId": 1344540,
"activityDateTime": "2018-03-01T13:31:52",
"viewMessageLink": "https://123.esclick.me/test"
}, {
"hardBounce": false,
"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
"contactId": 295953704,
"email": "test@rambler.ru",
"activityStatus": "UNDELIVERED",
"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"
},
{
"iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
"contactId": 318515138,
"email": "test@gmail.com",
"activityStatus": "READ",
"messageId": 1235215,
"messageInstanceId": 1622691,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T04:05:53",
"viewMessageLink": "https://123.esclick.me/test"
}, {
"iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
"contactId": 371353431,
"email": "test@gmail.com",
"activityStatus": "UNSUBSCRIBED",
"messageId": 1166457,
"messageInstanceId": 1550164,
"messageTag": "1521722870",
"activityDateTime": "2018-05-15T09:56:40",
"viewMessageLink": "https://123.esclick.me/test"
}, {
"iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
"contactId": 39781237,
"email": "test@gmail.com",
"activityStatus": "CLICKED",
"messageId": 1242672,
"messageInstanceId": 1630305,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T04:45:04",
"viewMessageLink": "https://123.esclick.me/test",
"clickEventLink": "https://test.ua/promo/"
},
{
"iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
"contactId": 351886894,
"email": "test@mail.ru",
"activityStatus": "SPAM",
"messageId": 1242672,
"messageInstanceId": 1630305,
"messageTag": "1522397496",
"activityDateTime": "2018-05-15T08:23:56",
"viewMessageLink": "https://123.esclick.me/test"
}
]

Возможные параметры:

Параметр

Тип

Описание

iid

string

Служебный параметр

contactId

int

Идентификатор контакта

email

string

Email контакта

activityStatus

string

DELIVERED - сообщение доставлено

UNDELIVERED - сообщение не доставлено (в параметре statusDescription описывается причина)

READ - сообщение прочитано

UNSUBSCRIBED - контакт отписался от рассылок

CLICKED - контакт переходил по ссылкам в сообщении

SPAM - контакт пожаловался на спам

messageId

int

Идентификатор сообщения

messageInstanceId

int

Идентификатор экземпляра сообщения

messageTag

string

Метка сообщения

activityDateTime

string

Дата и время, когда случилась активность

statusDescription

string

Это поле возвращается только в случае, если статус UNDELIVERED. Содержит причину, по которой сообщение не было доставлено. Это может быть ответ сервера получателя, ответ системы о невозможности отправить сообщение etc.

viewMessageLink

string

Содержит ссылку на веб-версию сообщения

clickEventLink

string

Содержит ссылку по которой перешел контакт (при статусе CLICKED)

hardBounce

bool

Это поле возвращается только в случае, если статус UNDELIVERED. Параметр оповещает о наличии контакта в черном списке.


false - не в черном списке на момент отправки сообщения
true - в черном списке на момент отправки

Практическое применение вебхуков

Данный функционал позволяет в режиме реального времени получать информацию о всех активностях контактах без запросов информации с вашей стороны. Информация будет поступать регулярно на указанный URL POST-запросами, как описано выше.
Для сравнения/альтернативы есть метод API v2/contacts/activity

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

Документация /api/methods.html#/v2/contacts/activity-GET

 

Контроль триггеров

Вы настроили передачу необходимых событий в систему eSputnik, создали письма, запустили нужные сценарии. Как контролировать триггеры и обезопасить себя от любых сбоев?

Есть 2 варианта отслеживания:

  • Частота поступления событий в систему;

  • Регулярность отправки писем, отмеченных определенными тегами.

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

События

События приходят в момент, когда пользователь совершил какое-либо действие на сайте или в письме. Событие запускает сценарий, т.е. выступает в роли триггера.

Возможна отправка письма на ваш электронный адрес или SMS с “предупреждением” или “тревогой”. Зайдите в настройки своего аккаунта и создайте уведомление.

Контроль триггеров в eSputnik

Настройка во всплывающем окне:

  1. В поле “Тип” выберите “Событие”;

  2. Выберите название события, по которому хотите получать уведомления;

  3. Укажите нижнюю границу по количеству событий для вашей компании;

  4. Обозначьте период, за который будет подсчитываться количество поступивших событий;

  5. Выберите уровень уведомления: предупреждение или тревога.

Контроль триггеров в eSputnik

Например, для события subscribeFromApi - менее 5 подписчиков в день является критичным и срабатывает сигнал “Тревоги”, с помощью которого вы понимаете, что нужно немедленно проверить настройки интеграции на своей стороне.

На это же событие можно одновременно поставить предупреждающий сигнал, который вам скажет о маленьком количестве поступающих ивентов о новых подписчиках. Например, менее 20 в день или в несколько дней.

Указанные лимиты зависят от показателей, которые есть нормой для вашего бизнеса. Вы можете поменять их в любой момент.

Контроль триггеров в eSputnik

Например, по событию new_order может срабатывать сценарий, который включает жизненно важную информацию для клиента: о заказе, оплате, доставке, транзакциях и т.д. Установите на подобные письма “Тревогу” с лимитом 1 и менее в сутки для оперативного решения возникших проблем.

Контроль триггеров в eSputnik

Уведомления можно применить ко всем существующим событиям в аккаунте и выбрать оба уровня в зависимости от указанного количества и периода отслеживания.

Теги

Тег - это слово, в широком смысле означающее метку или маркировочный знак. Слово tag переводится именно как «метка» или даже «ценник, этикетка», однако в системе eSputnik используется применительно к существующему списку писем, где может быть неограниченное количество промо и триггерных писем. Чтобы их различать и иметь возможность найти нужное и существуют теги.

Контроль триггеров в eSputnik

Тэги (tags, метки) – это такие маленькие специальные слова, которые вы видите справа от названия письма. Если кликнуть мышкой в такое слово, то у вас откроется подборка писем, что на определенную тему. Фактически, это тоже поисковик, но строго по данному списку ваших писем. Например, категории “промо”, “транзакции”, “триггера”, “польский язык”, “приветственная серия” и пр.

Контроль триггеров в eSputnik

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

  1. В поле “Тип” выберите “Тег”;

  2. Указать название (например, язык);

  3. Минимальное количество;

  4. Период;

  5. Уровень: предупреждение или тревога.

Настройка

После добавления уведомлений в настройках, во вкладке “История событий” появятся автоматически alertSettingsAlarmTrigger и alertSettingsWarningTriggerEvent. Это и есть приоритетность, о которой говорилось ранее.

  1. Создайте письмо с желаемой информацией, которая будет соответствовать цели уведомления - безопасности и быстрому реагированию;

Контроль триггеров в eSputnik

  1. Создайте сценарий с обязательным емейлом или SMS, укажите получателя;

Контроль триггеров в eSputnik

  1. Прикрепите событие к сценарию и запустите его.

Контроль триггеров в eSputnik

Контроль

Как только вы получили уведомление:

  1. Перейдите во вкладку “История событий” в аккаунте организации;

  2. Просмотрите параметры события, где указано название триггера;

  3. Проверьте интеграцию.

Контроль триггеров в eSputnik

Отслеживание вебхуков важно не только для проверки работы системы, а и спокойствия за ваших пользователей, которые бесперебойно получают нужную информацию. Нам важно, чтобы автоматизация была доступна маркетологам без помощи программистов. Для этого система eSputnik постоянно совершенствуется, чтобы позволить быстро и эффективно внедрять любые сценарии.