Вебхуки (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

Ідентифікатор контакту

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.
Надіслати email