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

Webhooks (рус. вебхуки) – это пользовательские обратные запросы по HTTP. Обычно их отработка связана с каким-либо событием, например, прочтением письма или запуском приветственной серии. Вебхуки считаются удобным инструментом для отслеживания событий в реальном времени: как только событие наступает, на внешний URL отправляется запрос.

В eSputnik есть два варианта для настройки и использования вебхуков:

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

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

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

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

При помощи вебхуков вы будете получать информацию обо всех событиях в любом канале:

• отправлено (только для канала Mobile Push);
• доставлено;
• ошибка доставки;
• прочитано;
• получатель перешел по ссылке;
• получатель отписался от рассылок;
• получатель пожаловался на спам;
• подписки, уникальные просмотры и конверсия для виджетов.

Как подключить вебхуки для аккаунта

Сконфигурируйте на своем сервере URL, на который вы хотите получать уведомления, POST запросы в формате JSON.

Затем этот URL внесите в настройки eSputnik. Для этого авторизуйтесь в системе, зайдите в настройки аккаунта → раздел “Лаборатория”. Активируйте опцию “Вебхуки” и вставьте ваш 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": {}
  }
]