Система уведомлений о событиях (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 — установить/заменить обработчик оповещений о событиях определенного типа.

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

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 — получить список всех обработчиков.

{
    "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 — удалить обработчик оповещений.

Формат оповещений (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-объект со следующими полями:

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

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

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

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

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

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

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

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

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