Вебхуки (Webhooks)

Общее описание

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

События, которые вы будете получать

На сегодняшний день при помощи вебхуков можно получать информацию о всех активностях пользователя после отправленных sms и emal-сообщений:

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

Как внедрить вебхуки?

Вам необходимо сконфигурировать на своем сервере 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 - контакт пожаловался на спам SUBSCRIPTION_CHANGED - контакт изменил категорию подписки
messageId	int	Идентификатор сообщения
messageInstanceId	int	Идентификатор экземпляра сообщения
messageTag	string	Метка сообщения
activityDateTime	string	Дата и время, когда случилась активность
statusDescription	string	Это поле возвращается только в случае, если статус UNDELIVERED. Содержит причину, по которой сообщение не было доставлено. Это может быть ответ сервера получателя, ответ системы о невозможности отправить сообщение etc.
viewMessageLink	string	Содержит ссылку на веб-версию сообщения
clickEventLink	string	Содержит ссылку по которой перешел контакт (при статусе CLICKED)
hardBounce	bool	Это поле возвращается только в случае, если статус UNDELIVERED. Параметр оповещает о наличии контакта в черном списке. false - не в черном списке на момент отправки сообщения true - в черном списке на момент отправки
statusData		Массив с данными
subscripton		Массив с данными
subscriptons	array of string	Ключи категорий подписок

Практическое применение вебхуков

Данный функционал позволяет в режиме реального времени получать информацию о всех активностях контактах без запросов информации с вашей стороны. Информация будет поступать регулярно на указанный URL POST-запросами, как описано выше.
Для сравнения/альтернативы есть метод API v2/contacts/activity

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

Документация /api/methods.html#/v2/contacts/activity-GET

Протестируйте на реальных рассылках