webhook/set

Метод для установки или редактирования обработчика оповещения о событиях. Оповещения можно получать в формате “json_post”, “json_post_gzip”.

Webhook могут оповещать о таких событиях:

  • отправленное письмо получило статус (статусы, о которых следует уведомлять, настраиваются при установке Webhook);

  • спам-блокировка

Тестовый запрос

POST /ru/transactional/api/v1/webhook/set.json
{
  "api_key": "apiKey",
  "url": "https:\/\/example.org",
  "status": "active",
  "event_format": "json_post",
  "delivery_info": 1,
  "single_event": 0,
  "max_parallel": 10,
  "events": 
  {
    "email_status":
    [
      "sent",
      "delivered",
      "opened",
      "hard_bounced",
      "soft_bounced",
      "spam",
      "clicked",
      "unsubscribed"
    ],
    "spam_block":
    ["*"]
  }
}

Пример удачного выполнения запроса


{
    "status": "success",
    "object": {
        "id": 1,
        "url": "https://example.org",
        "status": "active",
        "event_format": "json_post",
        "max_parallel": 10,
        "single_event": 0,
        "delivery_info": 1,
        "updated_at": "2020-12-08 11:02:27",
        "events": {
            "spam_block": [
                "*"
            ],
            "email_status": [
                "sent",
                "delivered",
                "opened",
                "hard_bounced",
                "soft_bounced",
                "spam",
                "clicked",
                "unsubscribed"
            ]
        }
    }
}

 

Параметры запроса

Название Тип Описание
api_key Обязательная строка API-ключ пользователя или проекта
url Обязательная строка Cтрока с URL, на который будет отправляться запрос при возникновении события (идентификатор обработчика). В URL поддерживаются пока только ASCII-символы. Если вам нужно использовать не-ASCII, сковертируйте URL в Punycode.
status Опциональная строка "active" или "disabled". Значение "stopped", хотя оно и валидное, передавать нельзя - его может установить только система в случае неработоспособности вашего обработчика в течение 24 часов (и как минимум после 10 запросов). В случае смены значения на "disabled" происходит прекращение генерации событий для вебхука и очистка очереди ещё не обработанных событий. В случае смены значения на "active" после "disabled" или "stopped" происходит возобновление генерации событий и вызовов вебхука. Если параметр status не передаётся, то считается, что передано значение "active".
event_format Опциональная строка Заданный формат, в котором будут присылаться оповещения. Либо "json_post", либо "json_post_gzip". Если параметр не передаётся, то считается, что передано значание "json_post".
delivery_info Опциональный 1/0 Принимает значения 1 и 0. По умолчанию: 0
  • 1 - детальная информация о доставке и причинах недоставки (если status равен hard_bounced или soft_bounced, будет возвращена информация о причинах недоставки; если status равен opened или clicked, будет возвращен ip-адрес получателя и информация о браузере и операционной системе получателя);
  • 0 - детальная информация о причинах недоставки (когда status = hard_bounced, soft_bounced, opened, clicked) не будет возвращена
single_event Опциональный 1/0 Принимает значения 1 и 0. По умолчанию: 0.
  • 1 - оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию;
  • 0 - оповещение Webhook возвращает информацию в виде массивов
max_parallel Опциональное целое число Максимальное количество параллельных запросов на сервер. Допустимые значения: от 5 до 100. По умолчанию: 10
events Опциональный объект Список установленных событий в виде объекта
events.email_status Опциональный массив Установленные статусы сообщений, по которым будут приходить уведомления
events.spam_block Опциональный массив Cобытия, связанные со спам-блокировкой

 

Поля успешного результата

Название Тип Описание
status Обязательная строка Значение "success"
object Обязательный объект Объект, который включает параметры оповещения
object.id Обязательное целое число Идентификатор обработчика
object.url Обязательная строка

Cтрока с URL, на который будет отправляться запрос при возникновении события

object.status Обязательная строка

Текущий статус обработчика:

  • active - обработчик активен и в рабочем состоянии
  • disabled - обработчик отключен пользователем
  • stopped - обработчик остановлен системой, т.к. принимающая сторона в течение последних 24 часов ни разу не отдала корректный ответ 200 OK (и при этом вызовов было не менее 10).
object.events Обязательный объект Список установленных событий в виде объекта
object.events.email_status Обязательный массив Установленные статусы сообщений, по которым будут приходить уведомления
object.events.spam_block Обязательный массив Cобытия, связанные со спам-блокировкой
object.event_format Обязательная строка Заданный формат, в котором будут присылаться оповещения
"json_post" или "json_post_gzip"
object.delivery_info Обязательный 1/0
  • 1 - детальная информация о доставке и причинах недоставки (если status равен hard_bounced или soft_bounced, будет возвращена информация о причинах недоставки; если status равен opened или clicked, будет возвращен ip-адрес получателя и информация о браузере и операционной системе получателя);
  • 0 - детальная информация о причинах недоставки (когда status = hard_bounced, soft_bounced, opened, clicked) не будет возвращена

object.updated_at

Обязательная строка Дата и время последнего обновления обработчика
object.single_event Обязательный 1/0
  • 1 - оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию;
  • 0 - оповещение Webhook возвращает информацию в виде массивов
object.max_parallel Обязательное целое число Максимальное количество параллельных запросов на сервер. Допустимые значения: от 5 до 100. По умолчанию: 10

 

Доступны следующие статусы для уведомления (значения переменной "email_status"):

sent — сообщение отправлено, но пока не доставлено.

delivered — сообщение доставлено. Может измениться на “opened” и “clicked”.

opened — сообщение доставлено и зарегистрировано его прочтение. Может измениться на “clicked”.

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

unsubscribed — сообщение было доставлено получателю и прочитано им, но пользователь отписался по ссылке в письме. Статус окончательный.

soft_bounced — не удалось доставить сообщение по одной из следующих причин:

  • попытки отправки не производились, или отправка отложена;

  • ящик адресата переполнен;

  • письмо было отвергнуто сервером получателя как спам;

  • было не менее одной попытки отправки, попытки продолжаются;

  • домен получателя не принимает почту из-за неправильных настроек;

  • отправка была отменена;

  • отправка отменена из-за некорректных данных отправителя;

  • не хватает средств на счету;

  • адрес временно недоступен.

hard_bounced — не удалось доставить сообщение по одной из следующих причин:

  • почтовый ящик адресата не существует, либо удален;

  • email-адрес не используется;

  • домен получателя не принимает никакую почту вообще по любой причине;

  • некорректный адрес получателя;

  • адресат отписался от Ваших рассылок;

  • email-адрес недоступен;

  • письмо превышает допустимый размер;

  • истек срок повторных отправок сообщения.

spam — сообщение доставлено, но отмечено “как спам” получателем. UniOne может получить и обработать жалобу о спаме (используя технологию fbl) от таких доменов:

  • mail.ru;
  • msn.com, outlook.com, hotmail.com, live.com;
  • ukr.net;
  • yahoo.com;
  • aol.com.

 

Поля ошибочного результата

status - строка "error"

message - сообщение об ошибке на английском

code - один из общих кодов ошибок.

Код Значение Как исправить
301 Формат события не поддерживается События должны быть в формате json_post
303 Список событий, переданный в запросе, содержит неподдерживаемое значение/событие не поддерживается Проверьте корректность ввода списка событий
304 Не удалось найти Webhook с указанным URL Убедитесь в правильности передаваемого URL
305 URL не передан Убедитесь в правильности передаваемого URL
306 Список событий пуст, либо пропущен Убедитесь в наличии списка событий в запросе
309 В параметре "max_parallel" передано значение не из диапазона доступных Используйте допустимое значение от 5 до 100
310 Параметр "max_parallel" должен быть числом Используйте допустимое значение от 5 до 100
2700 Ошибка в поле "url". Значение должно быть строкового типа. Передавайте строку в параметре "url"
2701 Ошибка в поле "url". Значение не должно быть пустым. Убедитесь, что URL указан в значении параметра
2702 Ошибка в поле "offset". Значение должно быть больше или равно 0 Установите значение параметра больше или равное 0.
2703 Ошибка в поле "eventFormat". Выбранное вами значение недопустимо Используйте только формат "json_post" или "json_post_gzip"
2704 Ошибка в поле "deliveryInfo". Значение "delivery_info" должно быть 1\0 либо true\false. Передавайте значение параметра "delivery_info" равным 1\0 либо true\false
2705 Ошибка в поле "singleEvent". Значение "single_event" должно быть 1\0 либо true\false. Передавайте значение параметра "single_event" равным 1\0 либо true\false
2706 Ошибка в поле "maxParallel". Значение должно иметь целочисленный тип Передавайте значение целочисленного типа в параметре "maxParallel"
2707 Ошибка в поле "maxParallel". Значение должно находиться в диапазоне от 5 до 100 Используйте допустимое значение от 5 до 100
2708 Ошибка в поле "events". Это значение должно быть массивом Убедитесь, что список событий в параметре "events" передан массивом
2709 Ошибка в поле "events". Значение не должно быть пустым Убедитесь, что в параметре "events" переданы значения
2710 Ошибка в поле "events". Поле "email_status" обязательно Убедитесь, что передан параметр "email_status"
2711 Ошибка в поле "email_status".Значение "test" недопустимо для 'email_status' Укажите верный статус сообщений 
2712 Ошибка в поле "spam_block". Значение "test" недопустимо для "spam_block" Укажите верное событие спам-блокировок
2713 Ошибка в поле "url". Домен для Webhook не найден. Убедитесь, что домен указан правильно
2714 Ошибка в поле "status". Недопустимое значение, статус может быть только "active" или "disabled" Укажите статус "active" или "disabled"
2715 Ошибка в поле "status". Это значение должно быть строкового типа Используйте строку для параметра "status"