Haskimail База знаний

Вебхуки

3 статьи Сергей От Сергей

Уведомления о доставке, возвратах, жалобах, открытиях, кликах и отписках в реальном времени.

Модульные вебхуки

Вебхуки Haskimail сообщают о событиях с вашими письмами в реальном времени: при каждом событии Haskimail отправляет HTTP POST-запрос с JSON на указанный вами URL. Поддерживаются шесть типов событий: 1. Доставка 2. Открытие 3. Клик 4. Изменение подписки 5. Возврат 6. Жалоба на спам Все шесть событий доступны и в транзакционных, и в маркетинговых каналах. Вебхуки настраиваются для каждого канала отправки. В канале можно добавить до 10 вебхуков и для каждого выбрать любой набор событий. Как добавить вебхук 1. Откройте сервер и нужный канал отправки. 2. Перейдите на вкладку Вебхуки. 3. Нажмите Добавить вебхук. 4. В поле URL вебхука укажите адрес, на который должны приходить события. 5. Отметьте нужные события. Вкладка «Вебхуки» канала отправки и кнопка «Добавить вебхук» Форма «Добавить вебхук»: поле «URL вебхука» и список событий Вебхуки можно настраивать и через API вебхуков. Как проверить вебхук Перед сохранением нажмите Отправить тест — на ваш URL придёт тестовое событие. Если для вебхука выбрано несколько событий, выберите нужное в списке рядом с кнопкой. Когда тест прошёл успешно, нажмите Сохранить вебхук внизу страницы. Как должен отвечать ваш сервер - Отвечайте кодом 2xx сразу после получения запроса, а тяжёлую обработку выполняйте потом. Haskimail ждёт ответа до 10 секунд. - Если ваш сервер ответил кодом 5xx, Haskimail повторит отправку — примерно раз в минуту, до 60 попыток. - При ответе 4xx, а также если сервер не ответил за 10 секунд, повторных попыток не будет. - Одно событие может прийти повторно. Чтобы не обработать его дважды, отличайте события по сочетанию полей event, message_id, recipient и event_time. Как защитить вебхук - Используйте HTTPS. - Проверяйте поле secret: это MD5-хеш от recipient, message_id и ключа подписи, записанных подряд без разделителей. Ключ подписи показан на вкладке Вебхуки любого канала, он один для всех вебхуков аккаунта. - При необходимости добавьте в URL логин и пароль для basic-авторизации. Подробнее — в документации по вебхукам. Пример проверки подписи PHP: $event = json_decode(file_get_contents('php://input'), true); $expected = md5($event['recipient'] . $event['message_id'] . $webhookKey); if (!hash_equals($expected, $event['secret'])) { http_response_code(403); exit; } Python: import hashlib, hmac def is_valid(event: dict, webhook_key: str) -> bool: raw = f"{event['recipient']}{event['message_id']}{webhook_key}" expected = hashlib.md5(raw.encode()).hexdigest() return hmac.compare_digest(expected, event['secret']) Если событие не связано с письмом, message_id в нём — пустая строка. Тестирование с Postman Проверить свой обработчик без реальных писем можно в Postman или любом другом HTTP-клиенте: отправьте на свой URL POST-запрос с примером JSON из документации.

Вебхуки для доставки

Вебхук доставки сообщает в реальном времени, что письмо принято почтовым сервером получателя. Так не нужно запрашивать статус доставки через API или проверять его в интерфейсе. Как подключить вебхук в интерфейсе 1. Откройте сервер, затем канал отправки, и перейдите на вкладку Вебхуки. Вкладка «Вебхуки» канала отправки и кнопка «Добавить вебхук» 2. Нажмите Добавить вебхук и укажите адрес в поле URL вебхука. 3. Отметьте событие DELIVERED (доставка) и нажмите Отправить тест, чтобы проверить вебхук. 4. Если тест прошёл успешно, сохраните вебхук. Форма «Добавить вебхук»: отмечено событие DELIVERED, кнопка «Отправить тест» Как подключить вебхук через API Событие доставки можно включить при создании или редактировании вебхука через API вебхуков. Пример события Haskimail отправляет на ваш URL POST-запрос с заголовком Content-Type: application/json: { "event": "delivered", "recipient": "ivan@example.com", "email": "ivan@example.com", "message_id": "a41d7c9e2b6f4e0d8c3b5a1f9e7d2c60", "code": "", "description": "", "error": "", "bounce_category": "", "user_id": "48213", "campaign_id": "orders", "member_id": "0", "event_time": "2026-10-07 14:30:15", "event_time_utc": "2026-10-07 11:30:15", "secret": "5f2b0c1d9a7e4c3b8d6f1a2e3c4b5d6e", "custom_vars": "{\"order_id\":\"1042\"}", "server_id": 11834, "stream_id": "2081" } Основные поля: - event — тип события, для доставки всегда delivered; - recipient — адрес получателя; - message_id — ID письма из ответа на отправку; - campaign_id — тег письма, если он был задан при отправке; - custom_vars — метаданные письма в виде строки с JSON; - event_time и event_time_utc — время доставки по Москве и в UTC; - server_id и stream_id — ID сервера и канала; - secret — подпись для проверки подлинности запроса. Поля code, error, description и bounce_category заполняются только в вебхуках возвратов. Обратите внимание: статус «доставлено» означает, что письмо принял почтовый сервер получателя. Попало ли оно во «Входящие» или в спам, по этому событию узнать нельзя. Полное описание — в документации по вебхуку доставки. Как Haskimail повторяет отправку и как защитить вебхук — в статье «Модульные вебхуки».

Вебхуки для возвратов

Вебхук возвратов сообщает в реальном времени о каждом письме, которое не удалось доставить. Haskimail отправляет HTTP POST-запрос с JSON на URL, указанный в настройках канала отправки. Вебхук возвратов работает и в транзакционных, и в маркетинговых каналах. Пример тела запроса: { "event": "bounced", "recipient": "old-address@example.com", "email": "old-address@example.com", "message_id": "a41d7c9e2b6f4e0d8c3b5a1f9e7d2c60", "code": "550", "description": "550 5.1.1 The email account that you tried to reach does not exist", "error": "550 5.1.1 The email account that you tried to reach does not exist", "bounce_category": "hrd", "user_id": "48213", "campaign_id": "orders", "member_id": "0", "event_time": "2026-10-07 14:30:15", "event_time_utc": "2026-10-07 11:30:15", "secret": "5f2b0c1d9a7e4c3b8d6f1a2e3c4b5d6e", "custom_vars": "{\"order_id\":\"1042\"}", "server_id": 11834, "stream_id": "2081" } Основные поля: - event — тип события, для возврата всегда bounced; - recipient — адрес, на который не удалось доставить письмо; - bounce_category — тип возврата: hrd — жёсткий возврат, sft — мягкий возврат, blk — блокировка сервером получателя (по его политике или из-за репутации отправителя), spm — письмо отклонено спам-фильтром из-за содержания; - code и error — код и текст ответа почтового сервера; - message_id — ID письма из ответа на отправку; - campaign_id — тег письма; - custom_vars — метаданные письма в виде строки с JSON; - event_time и event_time_utc — время события по Москве и в UTC; - secret — подпись для проверки подлинности запроса. Все значения, кроме server_id, передаются строками. Полное описание полей — в документации. Как использовать вебхук возвратов - Сообщать отправителю или пользователю, что письмо не доставлено. - Помечать недействительные адреса в своей базе и не отправлять на них письма. - Следить за ростом возвратов. - Связываться с получателем другим способом, чтобы узнать новый адрес. Как подключить вебхук Сначала подготовьте на своём сервере обработчик, который принимает POST-запросы с JSON и отвечает кодом 2xx. Затем: 1. Откройте сервер и канал отправки. 2. Перейдите на вкладку Вебхуки и нажмите Добавить вебхук. 3. Укажите URL в поле URL вебхука. 4. Отметьте событие BOUNCED (возвраты) и нажмите Отправить тест. 5. Если тест прошёл успешно, сохраните вебхук. Вкладка «Вебхуки» канала отправки и кнопка «Добавить вебхук» Форма «Добавить вебхук»: отмечено событие BOUNCED Как Haskimail повторяет отправку и как защитить вебхук — в статье «Модульные вебхуки». Как протестировать Отправьте письмо на один из тестовых адресов, например hardbounce@bounce-testing.haskimail.ru или softbounce@bounce-testing.haskimail.ru. Haskimail создаст тестовый возврат и вызовет вебхук. Такие письма не влияют на вашу репутацию. Все тестовые адреса — в статье «Как тестировать письма перед отправкой».