Вебхуки для відстеження активності

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

В eSputnik є два способи для налаштування та використання вебхуків:

1. Додавання зовнішнього URL для аккаунту, щоб відслідковувати активності користувачів.
2. Налаштування кастомних запитів в сценаріях через спеціальний блок Webhook.

Вебхуки для відстежування активностей

Ця функціональність дозволяє в режимі реального часу отримувати інформацію про всі активності контактів. Дані надходитимуть регулярно на вказаний URL POST запитами, як описано нижче.

Для порівняння/альтернативи є метод API Get contacts activity. Він працює при надсиланні з вашого боку GET запитів, в яких можна вказувати інтервал часу (не більше 3 місяців) та параметри (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 з усіма можливими варіантами статусів. 

Для масових розсилок:

[
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "test1@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB",
    "statusData": {}
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "test2@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB",
    "statusData": {}
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4",
    "contactId": 1026901517,
    "email": "test3@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB",
    "statusData": {}
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "hardBounce": false,
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "test1@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "UNDELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:07",
    "statusDescription": "5.1.2 (bad destination system: no such domain)",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB",
    "statusData": {}
  }
]

Для тригерних розсилок:

[
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_05cae26d9ae85e1eb40ed34765f9c7be",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "019b7450-52d9-11ee-85c4-959256ea468c",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "test1@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:50",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P",
    "statusData": {}
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_527e1f819b41bd379d75ebbe3392b879",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "01777190-52d9-11ee-917a-ef6e91bfc7c3",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "test1@yourdomain.com",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:51",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP",
    "statusData": {}
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_be178ec8aacbf249d8bb736e9df9fd0d",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "hardBounce": false,
    "iid": "01a86ca0-52d9-11ee-85c4-959256ea468c",
    "contactId": 706515632,
    "sms": "380956490955",
    "mediaType": "viber",
    "activityStatus": "UNDELIVERED",
    "messageId": 3213684,
    "messageInstanceId": 4696769,
    "messageTag": "tag2,tag,test",
    "activityDateTime": "2023-09-14T08:30:51",
    "statusDescription": "401: null",
    "statusData": {}
  }
]

Практичне застосування вебхуків

Цей функціонал дозволяє отримувати в режимі реального часу інформацію про всі активності контакту без запитів інформації з вашого боку. Інформація надходитиме регулярно на вказаний URL POST-запитами, як описано вище.

Для порівняння/альтернативи існує метод API Get contacts activity.

Він працює при відправленні з вашого боку GET-запитів, у яких можна вказувати інтервал часу (не більше 3 місяців) і параметрів (email, статус тощо).

Документація: https://docs.esputnik.com/reference/contactactivity-1