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.
Установить обработчик
установить / заменить обработчик оповещений о событиях определенного типа.
Синтаксис и URL для вызова метода |
setHook (hook_url, events, [event_format, max_parallel]) |
https://api.unisender.com/ru/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM |
Аргументы | |||||||||||||||||||
api_key* | ключ доступа к API | ||||||||||||||||||
hook_url * | на какой URL отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены | ||||||||||||||||||
event_format | формат, в котором передаются данные о событии, обязательный параметр с тремя вариантами значений:
|
||||||||||||||||||
events* | ассоциативный массив, перечисляющий оповещения, которые получает обработчик. Ключами массива могут быть строки:
|
||||||||||||||||||
max_parallel | необязательное указание максимального количество параллельных вызовов к этому обработчику. По умолчанию равно 10. | ||||||||||||||||||
single_event | Принимает значения 1 и 0. По умолчанию: 0
1 — оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию; |
Пример вызова
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 — получить список всех обработчиков.
Синтаксис и 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"] } }] } |
Удалить обработчик
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-объект со следующими полями:
массив из 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_data | Описание |
email_status |
|
unsubscribe |
|
campaign_status |
|
email_check | email — Email, право использования которого в качестве обратного адреса подтверждено пользователем. |
user_payment |
|
user_info |
|