Вебхуки (Webhooks)

Загальний опис

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

Події, які ви будете отримувати

Сьогодні за допомогою вебхуків можна отримувати інформацію про всі активності користувача після відправлених sms та 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"
        ]
      }
    }
  },
  {
    "broadcastId": 2833914,
    "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"
  },
  {
    "broadcastId": 2833915,
    "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"
  },
  {
    "broadcastId": 2833914,
    "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"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
    "contactId": 1258810400,
    "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"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
    "contactId": 1258810400,
    "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"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
    "contactId": 1258810400,
    "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/"
  },
  {
    "workflowId": 245460,
    "workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
    "sourceEventKey": "1258810400",
    "sourceEventTypeKey": "subscribeFromApi",
    "iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
    "contactId": 1258810400,
    "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"
  }
]

Можливі параметри:

Параметр

Тип

Опис

broadcastId

int

Ідентифікатор розсилки

workflowId

int

Ідентифікатор сценарія

workflowBlockId

string

Службовий параметр сценарія

sourceEventKey

string

Ключ типу події

sourceEventTypeKey

string

Значення ключа події

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