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

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

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

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

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

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

• прочитано;

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

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

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

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

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

После начнется мгновенная проверка 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"
}
]

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

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

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

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

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

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

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

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

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

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

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

События

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

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

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

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

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

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

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

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

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

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

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

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

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

Теги

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

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

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

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

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

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

4. Период;

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

Настройка

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

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

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

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

Контроль

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

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

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

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

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