Система сповіщень про події (Webhooks)

Webhook — механізм сповіщення користувачів системи про події. Події, про які може повідомляти Webhook:

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

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

Модель, яка використовується в Webhook, працює так: у разі виникнення події встановлений раніше обробник надсилає JSON на URL, зазначений для цього Webhook. Використовуються стандартні порти: 80 порт для HTTP та 443 порт для HTTPS. Для установки Webhook на URL із зазначеним портом можна передавати URL у вигляді: https://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.selzy.com/ua/api/setHook?api_key=XXX&hook_url=https%3A%2F%2Fmycompany.com%2Fselzy-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/selzy-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":"[email protected]", 
            "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":"[email protected]", 
            "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":"[email protected]", 
            "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 виникали помилки, клікніть на пункт «Історія помилок», щоб їх переглянути.