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

Вебхуки — це метод відстеження в реальному часі активності контактів у системі eSputnik і надсилання сповіщень про цю активність на URL-адресу клієнта.

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

Система надсилає запити на ваш сервер щоразу, коли відбувається одна з таких подій:

• Відправлено — повідомлення відправлено контактові (тільки для каналу Mobile Push);
• Доставлено — повідомлення надійшло контактові;
• Не доставлено — повідомлення не було доставлено;
• Читали — контакт відкрив повідомлення;
• Відписалися — контакт відмовився від розсилки;
• Переходили — контакт натиснув на посилання в повідомленні;
• Спам — повідомлення відзначене як спам;
• Змінено підписку — контакт змінив категорію підписки на розсилку.

📘

Примітка

Перед налаштуванням вебхуків необхідно сконфігурувати на своєму сервері URL, на який ви бажаєте отримувати повідомлення — POST-запити у форматі JSON, а також забезпечити їх обробку.

Створення експорту даних

Перейдіть у налаштування акаунта на вкладку Експорт даних, натисніть кнопку Новий експорт даних і виберіть Вебхук.

Підключення

Додайте назву вебхука і вкажіть URL-адресу, яку ви раніше підготували на своєму сервері.

Аутентифікація (опційно)

Якщо на вашому сервері увімкнено аутентифікацію, вкажіть логін і пароль, що їх використовує ваш сервер для приймання запитів. Для цього активуйте перемикач Authentication і заповніть відповідні поля.

Заголовки

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

1. Натисніть + Додати заголовок.

2. Введіть Ключ та Значення.

Усі вказані заголовки будуть автоматично додаватися до запитів вебхука.

Експорт статусів активності

За замовчуванням обрані всі статуси. За потреби ви можете змінити перелік — зніміть прапорці біля непотрібних.

Після налаштування експорту натисніть кнопку Зберегти.

Вебхук стане активним, і дані надходитимуть у реальному часі на зазначену URL-адресу.

Тестування інтеграції вебхука

Після налаштування вебхука ви можете перевірити його роботу без запуску реальної події.

1. На вкладці Експорт даних через вебхук натисніть кнопку Відправити тест.

2. У вікні Тестування інтеграції відкриється тестовий запит, який містить демонстраційний масив із кількох об'єктів — приклад того, як система формує вебхуки для різних каналів.

Ви можете змінити вміст запиту вручну, щоб перевірити роботу свого обробника з іншим форматом даних. Наприклад, змінити значення полів, видалити або додати елементи масиву тощо.

Усі задані заголовки будуть включені в тестовий запит, якщо вони були вказані.

3. Натисніть Готово.

4. Система миттєво надішле тестовий POST-запит на вказаний URL і відобразить результат перевірки:

• якщо сервер приймає запит успішно — з'явиться зелена плашка зі згорнутою секцією деталей;

• якщо сервер повертає помилку (наприклад, 403) — відобразиться червона плашка з кодом відповіді та розгорнутими деталями для аналізу.

Деталі запиту та відповіді можна скопіювати до буфера обміну.

Після тестування:

• натисніть Зберегти та закрити, якщо тестування пройшло успішно й вебхук працює коректно;
• якщо сталася помилка — натисніть Повторити спробу або натисніть Закрити, внесіть зміни до налаштувань і відправте тестовий запит ще раз.

Деактивація / Видалення вебхука

Щоб деактивувати або видалити вебхук, натисніть значок із трьома крапками, виберіть потрібний варіант і підтвердьте дію.

📘

Примітка

Деактивація призупиняє надсилання запитів, але сам вебхук зберігається в системі, і його можна повторно активувати пізніше.

Редагування експорту даних

Щоб змінити налаштування, натисніть назву вебхука, відредагуйте параметри та збережіть їх.

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

📘

Зверніть увагу

Теги для листів, надісланих через API, підтримуються (наприклад, через масив tags у методі v1/messages/email) — якщо їх немає у даних вебхука активності, перевірте, чи ваша інтеграція коректно передає поле tags. Тему листа можна отримати методом contactmessages, але лише для листів, складених у системі, а не для сирого HTML, надісланого напряму через API.

Нижче наведено тестові приклади вебхуків у вигляді масиву JSON з усіма можливими варіантами статусів. 

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

[
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4",
    "contactId": 1026901517,
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "hardBounce": false,
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "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"
  }
]

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

[
  {
    "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": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:50",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P"
  },
  {
    "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": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:51",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP"
  },
  {
    "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"
  }
]

Усунення проблем

Дедублікація однакових оновлень

Якщо протягом 1 хвилини надходить кілька оновлень з ідентичним тілом запиту, система об'єднує їх і не надсилає повторний вебхук для кожного дубліката. Самі події при цьому не дедублікуються лише за часом виникнення — враховується саме збіг вмісту оновлення в межах цього вікна.

Дублікати подій від WooCommerce

Плагін WooCommerce може двічі надіслати одну й ту саму подію PurchasedItems для одного замовлення — один раз при оформленні замовлення, і ще раз, якщо клієнт перезавантажить сторінку успішної оплати. eSputnik усуває дублікати замовлень за ключовими полями замовлення (наприклад, externalOrderId) — якщо надходить дублікат з тим самим значенням, він не записується повторно. Якщо ви створюєте власний обробник вебхуків для подій замовлень, застосуйте таку саму логіку усунення дублікатів на своєму боці, використовуючи externalOrderId (або аналогічний ідентифікатор ідемпотентності), щоб уникнути подвійного підрахунку.

Деталі налаштування — у статті Встановлення плагіна WooCommerce.

Альтернативні методи отримання статусів активності

eSputnik пропонує три способи отримання даних про активність у ваші власні системи — оберіть залежно від того, як плануєте використовувати ці дані:

📘

Примітка

Інтерфейс акаунту (картка контакту) зберігає лише останню дату відкриття й переходу для кожного контакту, а не повну історію. Якщо потрібна перша дата відкриття/переходу або повна хронологія, використовуйте вебхуки (щоб будувати повний журнал активності по мірі надходження подій) або методи API/BigQuery вище.

API Get contacts activity активується за запитом — зверніться в підтримку, щоб увімкнути його для вашого акаунту. Після активації він підтримує фільтрацію за контактом, наприклад за параметром email, на додачу до статусу й інтервалу часу.