Вебхуки (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": "ffd3e1a7-a270-4e58-94de-5ac681c5c8e7",
    "contactId": 687266822,
    "activityStatus": "SUBSCRIPTION_CHANGED",
    "mediaType": email,
    "activityDateTime": "2019-09-26T14:45:18",
    "statusData": {
      "subscription": {
        "subscriptions": [
          "SMARTPHONES",
          "TABLETS",
          "LAPTOPS"
        ]
      }
    }
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
    "contactId": 318515138,
    "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"
  },
  {
    "iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
    "contactId": 371353431,
    "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"
  },
  {
    "iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
    "contactId": 39781237,
    "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/"
  },
  {
    "iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
    "contactId": 351886894,
    "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"
  }
]

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

Параметр

Тип

Описание

iid

string

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

contactId

int

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

mediaType

string

Тип медиа-канала. Возможные варианты: email, sms, viber, mobilepush, webpush

email

string

Email контакта

sms

int

Номер телефона контакта

activityStatus

string

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

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

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

SUBSCRIPTION_CHANGED - изменения в категориях подписки

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

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

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

messageId

int

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

messageInstanceId

int

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

messageTag

string

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

activityDateTime

string

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

statusDescription

string

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

viewMessageLink

string

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

clickEventLink

string

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

statusData

string

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

hardBounce

bool

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


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

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

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

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