Вебхуки (Webhooks)
Общее описание
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"
}
]
Возможные параметры:
|
Параметр |
Тип |
Описание |
|
iid |
string |
Служебный параметр |
|
contactId |
int |
Идентификатор контакта |
|
|
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. Параметр оповещает о наличии контакта в черном списке.
|
Практическое применение вебхуков
Данный функционал позволяет в режиме реального времени получать информацию о всех активностях контактах без запросов информации с вашей стороны. Информация будет поступать регулярно на указанный URL POST-запросами, как описано выше.
Для сравнения/альтернативы есть метод API v2/contacts/activity
Он работает при отправке с вашей стороны GET запросов, в которых можно указывать интервал времени (не более 3 месяцев) и параметров (email, статус и т.д.).
Документация /api/methods.html#/v2/contacts/activity-GET