Система уведомлений о событиях (Webhooks)

Webhook — механизм оповещения пользователей системы о событиях. События, о которых может уведомлять Webhook:

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

Webhook используют для отслеживания изменения статусов писем в реальном времени.

Модель, используемая в Webhook, работает следующим образом: при возникновении события установленный ранее обработчик отправляет JSON на URL, который был указан для этого Webhook. Используются стандартные порты: 80 порт для HTTP и 443 порт для HTTPS. Для установки Webhook на URL с указанным портом можно передавать URL в виде: http://11.111.111.11:80

Если URL, на который отправляется Webhook, недоступен (отвечает не HTTP 200 OK, таймаут — 3 секунды), попытки отправки Webhook на этот URL до получения ожидаемого 200 ОК будут продолжаться в течение 24 часов с интервалом в 10 минут с дополнительным параметром retry_count, значение которого будет увеличиваться на 1 с каждой повторной отправкой Webhook.

Если в течение 24 часов вебхук не удалось доставить, попытки отправки прекращаются, а статус вебхука меняется на stopped. На почту аккаунта отправляется уведомление об остановке вебхука с указанием последнего ответа. Чтобы активировать остановленный вебхук, исправьте ошибку, затем включите вебхук с помощью API метода setHook с параметром status="active" или смените статус в личном кабинете.

Установить обработчик

setHook — установить/заменить обработчик оповещений о событиях определенного типа.

Синтаксис и URL для вызова метода
setHook (hook_url, events, [event_format, max_parallel, single_event, status])
https://api.unisender.com/ru/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM&single_event=1&status=active
Аргументы
api_key* ключ доступа к API
hook_url * на какой URL отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены.
event_format формат, в котором передаются данные о событии, обязательный параметр с тремя вариантами значений:

  • json_post — параметры оповещения будут переданы в теле POST-запроса в JSON-формате, возможна группировка сразу нескольких событий разных типов в одном запросе;
  • json_post_gzip— рекомендованный способ. Совпадает с json_post, только тело POST-запроса сжато с помощью gzip;
  • http_get— устаревший вариант, параметры оповещения передаются как GET-параметры HTTP-запроса, не поддерживается событие email_status
events* ассоциативный массив, перечисляющий оповещения, которые получает обработчик. Ключами массива могут быть строки:

Ключ массива Описание
email_status Изменение статуса отправленного email.

Допустимые значения:

ok_sent — письмо отправлено;
ok_delivered — письмо доставлено;
ok_read— письмо прочитано;
ok_link_visited — зафиксирован переход по ссылке
err_will_retry— письмо не доставлено, но будут попытки отправить его повторно.

Другие допустимые значения можно посмотреть здесь.

Разрешается использовать только с форматами json_post_gzip и json_post, и запрещается с форматом http_get.

unsubscribe Изменение статуса подписки получателя (отписался от списка).

Допустимое значение:*

subscribe Изменение статуса подписки получателя (подписался на список).

Допустимые значения:

* — отправлять при подписке на любой список
id списка — отправлять при подписке на список с заданным id

subscribe_primary Изменение статуса подписки получателя (подписался на список впервые)

Допустимые значения:

* — отправлять при подписке на любой список
id списка - отправлять при подписке на список с заданным id

campaign_status Изменение статуса массовой рассылки.

Допустимое значение: *

email_check Добавление подтвержденного обратного адреса.

Допустимое значение: *

user_payment Доступен только для реселлеров. Изменение состояния счета. Учитываются движения, связанные с основным и бонусным счетом.

Допустимое значение: *

user_info Изменение полей информации о пользователе.

Допустимое значение: *

max_parallel необязательное указание максимального количество параллельных вызовов к этому обработчику. По умолчанию равно 10.
single_event Принимает значения 1 и 0. По умолчанию: 0

1 — оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию;
0 — оповещение Webhook возвращает информацию в виде массивов (см. пример ниже).

status Статус обработчика. Допустимые значения: active — обработчик активен; disabled — обработчик отключён.

Пример вызова

https://api.unisender.com/ru/api/setHook?api_key=XXX&hook_url=https%3A%2F%2Fmycompany.com%2Funisender-hook&event_format=json_post_gzip&events[unsubscribe]=*&events[email_status]=ok_read,ok_link_visited&single_event=1&status=active

Список обработчиков

listHooks — получить список всех обработчиков.

Синтаксис и URL для вызова метода
listHooks ()
https://api.unisender.com/ru/api/listHooks?api_key=KEY
Аргументы
api_key * ключ доступа к API
Возвращаемое значение
{
    "result":
        [{
            "id":3,
            "url":"https://site.com/unisender-hook",
            "event_format":"json_post_gzip",
            "max_parallel":1,
            "single_event":0,
            "events":
                {
                    "subscribe": ["1","2","3"]
                },
            "status": "active"
         }]
    }

Удалить обработчик

removeHook — удалить обработчик оповещений.

Синтаксис и URL для вызова метода
removeHook (hook_url)
https://api.unisender.com/ru/api/removeHook?api_key=KEY&hook_url=URL
Аргументы
api_key * ключ доступа к API
hook_url* URL-идентификатор удаляемого обработчика

Формат оповещений (JSON)

Пример возвращаемого оповещения

{ 
  "auth":"6931402abc4b2a76b9719d911017c592", 
  "num":"12", 
  "events_by_user": 
  [ 
    { 
      "login":"user_zz", 
      "Events":
      [ 
        { 
          "event_name":"email_status", 
          "event_time":"2015-04-24 15:18:34", 
          "event_data": 
          { 
            "email":"user@example.com", 
            "campaign_id":"124345", 
            "status":"ok_read", 
            "status_group":"success_group",
            "delivery_info":
            {
              "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36",
              "ip":"111.111.111"
            } 
          } 
        }, 
        { 
          "event_name":"email_status", 
          "event_time":"2015-04-24 15:18:36", 
          "event_data": 
          { 
            "email":"user2@example.com", 
            "email_id":"346134", 
            "status":"ok_link_visited", 
            "status_group":"success_group",
            "delivery_info":
            {
              "user_agent":"Mozilla/5.0 (X11; Linux x86_64)",
              "ip":"111.111.111"
            }
          } 
        }, 
        { 
          "event_name":"unsubscribe", 
          "event_time":"2015-04-24 15:18:58", 
          "event_data": 
          { 
            "email":"user2@example.com", 
            "campaign_id":"87434", 
            "list_id":"3346", 
            "Just_unsubscribed_list_ids":
            [ 
              "3346", "7473" 
            ], 
            "Just_subscribed_list_ids":
            [ 
              "9745" 
            ] 
          } 
        } 
      ] 
    } 
  ] 
} 

Описание параметров оповещения (для single_event = 0)

Оповещения форматов json_post и json_post_gzip отправляются в виде POST-запроса на URL оповещения без дополнительных аргументов с Content-Type=application/json (и для json_post_gzip с Content-Encoding: gzip). В случае выбора формата json_post_gzip , необходимо проводить декомпрессию GZIP объекта перед чтением JSON. JSON-объект передается в теле запроса без задания каких-либо переменных, для чтения данных. К примеру, на PHP можно использовать команды: gzdecode($postData) — для декомпрессии GZIP; file_get_contents('php://input') — для чтения JSON.

Данные оповещения — JSON-объект со следующими полями:

Параметр

Описание

auth MD5-хэш строкового тела сообщения, в котором значение auth заменено на api_key пользователя, чей обработчик вызывается. С помощью этого оповещения получатель может как провести аутентификацию, так и проверить целостность оповещения.

Для генерации auth нужно сформировать полностью тело оповещения в JSON, вместо значения auth подставить значение api_key пользователя и вычислить md5 от тела. Затем заменить в сообщении api_key на получившийся md5, записанный в шестнадцатеричном виде в lowercase.

Для проверки auth надо заменить его значение на api_key, также вычислить md5 от тела оповещения и сверить его со значением auth, полученном в изначальном теле оповещения.

num на какой URL в формате punycode отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены.
events_by_user массив из JSON-объектов, каждый элемент которого соответствует одному пользователю. Более одного элемента в этом массиве может быть только для реселлеров — реселлеры могут получить уведомление о событиях сразу нескольких своих пользователей в одном вызове, в остальных случаях этот массив состоит из одного элемента.
login логин пользователя, оповещение о событиях которого мы передаём в рассматриваемом элементе массива events_by_user.
events массив событий пользователя с вышеуказанным логином, каждый элемент массива имеет следующие поля:

event_name имя события: email_check, unsubscribe, activate, reject, campaign_status, user_payment, user_info, email_status
event_time время возникновения события в формате "YYYY-MM-DD hh:mm:ss" в часовом поясе UTC.
event_data объект с данными события, формат которых зависит от имени события. Форматы описаны ниже.
Формат event_data Описание
email_status
  • email — email контакта, статус доставки сообщения по которому изменён.
  • email_id — идентификатор сообщения, полученный через sendEmail. Только для сообщений, отправленных через sendEmail.
  • campaign_id — идентификатор рассылки. Только для сообщений, отправленных через createCampaign.
  • status — статус доставки сообщения.
  • status_group — группа статуса в соответствии с названиями из результатов отправки email: "not_sent_group", "not_allowed_group" и т.п.
unsubscribe
  • email — email отписавшегося.
  • campaign_id — идентификатор рассылки, по письму из которой произошла отписка.
  • list_id — либо "0", либо код списка, по которому было отправлено письмо, после которого произошла отписка. "0" означает, что выполнена отписка от всех списков.
  • just_unsubscribed_list_ids — необязательный массив кодов списков, от которых только что произошла отписка. Отсутствует в случае, если была глобальная отписка от всех списков.
  • just_subscribed_list_ids — необязательный массив кодов списков, на которые только что подписались (на странице отписки можно и вернуть подписку). Отсутствует в случае, если отписка была от всех списков или ни на что не подписались.
campaign_status
  • campaign_id — идентификатор рассылки, который был возвращён вызовом метода createCampaign;
  • status - статус рассылки.
  • contact_count — количество контактов в рассылке.
  • period_messages — количество сообщений, отправленных за счёт включённых в период. Для SMS-сообщений всегда равно 0.
  • prepaid_messages — количество сообщений, отправленных за счёт ранее купленных;
  • pay_sum — сумма за отправку писем.
  • currency — трёхбуквенный международный код валюты, в которой посчитана сумма за отправку писем (RUB, USD, EUR, UAH).
email_check Email, право использования которого в качестве обратного адреса подтверждено пользователем.
user_payment
  • sum;
  • sum_bonus;
  • currency;
  • description;
  • new_balance;
  • new_balance_bonus.
user_info
  • email;
  • firstname;
  • middlename;
  • phone;
  • company;
  • timezone;
  • master;
  • country;
  • language;
  • rights.

Управление вебхуками в личном кабинете

В личном кабинете кликните на ваш email в правом верхнем углу и выберите «Настройки».

Меню «Настройки»

На панели слева перейдите в раздел «Webhook».

Раздел «Webhook»

Здесь отображаются:

  • ID вебхука.
  • URL, на который установлен вебхук.
  • Количество одновременных запросов.
  • События, о которых оповещает вебхук.
  • Статус вебхука — active, disabled или stopped.
  • Кнопка удаления вебхука.
  • История ошибок, если они есть.

Раздел «Webhook»

Если нужно выключить активный вебхук, кликните на active.

Выключить активный вебхук

Чтобы активировать выключенный вебхук, кликните на disabled.

Активировать выключенный вебхук

Если вебхук остановлен из-за ошибок, для активации нажмите на stopped.

Активировать остановленный из-за ошибок вебхук

Если при отправке вебхуков на ваш URL возникали ошибки, кликните на пункт «История ошибок», чтобы их посмотреть.

История ошибок

Вы нашли ответ?

11
26