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

Синтаксис і URL для виклику методу
setHook (hook_url, events, [event_format, max_parallel, single_event, status])
https://api.selzy.com/ua/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.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 — отримати список усіх обробників.

Синтаксис і URL для виклику методу
listHooks ()
https://api.selzy.com/ua/api/listHooks?api_key=KEY
Аргументи
api_key * ключ доступу до API
Зворотне значення
{
    "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 — видалити обробник повідомлень.

Синтаксис і URL для виклику методу
removeHook (hook_url)
https://api.selzy.com/ua/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":"[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-об'єкт із такими полями:

Опис

Опис

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 данные обработчика будет заменены.на який 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 — трилітерний міжнародний код валюти, яку використали для підрахунку суми за відправку листів (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.
  • Кнопка видалення вебхука.
  • Історія помилок, якщо вони є.

Якщо потрібно вимкнути активний вебхук, клікніть на active.

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

Щоб активувати вимкнений вебхук, клікніть на disabled.

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

Якщо вебхук зупинено через помилки, для активації натисніть на stopped.

Якщо під час відправки вебхуків на Ваш URL виникали помилки, клікніть на пункт «Історія помилок», щоб їх переглянути.

Ви знайшли відповідь на ваше питання?

0
0