Система уведомлений о событиях (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.

• Установить обработчик
• Список обработчиков
• Удалить обработчик
• Формат оповещения (JSON)

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

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

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

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

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

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"]
                }
         }]
    }

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

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", 
            "user_campaign_id":"346134", 
            "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", 
            "user_campaign_id":"camp-5464", 
            "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-объект со следующими полями:

массив из JSON-объектов, каждый элемент которого соответствует одному пользователю. Более одного элемента в этом массиве может быть только для реселлеров — реселлеры могут получить уведомление о событиях сразу нескольких своих пользователей в одном вызове, в остальных случаях этот массив состоит из одного элемента.

Пример на PHP

class hook {
    public function handle($receiver_path)
    {
        $filename = basename($receiver_path, '.php');
        $api_key = '';
        $postData = file_get_contents('php://input');
        if (strlen($postData) > 0) {
            $decodedData = json_decode($postData, true);
            if ($decodedData == '') {
                $decodedData = json_decode(gzdecode($postData), true);
            }
            $hash = $decodedData['auth'];
            $decodedData['auth'] = $api_key;
            file_put_contents('/tmp/__' . $filename . '__'
                . time() . md5(rand(0, 100000000)) . '.log', "
---------------Received message: ------------------\n" . var_export
                ($decodedData, true)
                . "\n\n Hash received: {$hash}\n Hash verifying: "
                . md5(json_encode($decodedData)), FILE_APPEND);
        } else {
            $actual_link = "https://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URL]";
            file_put_contents('/tmp/GET__' . $filename . '__'
                . time() . md5(rand(0, 100000000)) . '.log', $actual_link, FILE_APPEND);
            echo 'Yep! It works! Filename: ' . $filename;
        }
    }
}

require 'hook.php';
$h = new hook;
$h->handle(__FILE__);