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

Вебхуки Haskimail сообщают о событиях с вашими письмами в реальном времени: при каждом событии Haskimail отправляет HTTP POST-запрос с JSON на указанный вами URL. Поддерживаются шесть типов событий:

1. Доставка
2. Открытие
3. Клик
4. Изменение подписки
5. Возврат
6. Жалоба на спам

Все шесть событий доступны и в транзакционных, и в маркетинговых каналах.

Вебхуки настраиваются для каждого канала отправки. В канале можно добавить до 10 вебхуков и для каждого выбрать любой набор событий.

Как добавить вебхук

1. Откройте сервер и нужный канал отправки.
2. Перейдите на вкладку Вебхуки.
3. Нажмите Добавить вебхук.
4. В поле URL вебхука укажите адрес, на который должны приходить события.
5. Отметьте нужные события.

Вебхуки можно настраивать и через 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 из документации.