Вебхук — это когда Haskimail отправляет HTTP POST-запрос на API вашего приложения при возникновении определенного события. Таким образом, Haskimail может немедленно уведомлять вас о событии, и вашему приложению не нужно постоянно опрашивать API Haskimail, чтобы определить, произошло ли что-то новое.
Запрос приходит с заголовком Content-Type: application/json. Тип события указан в поле event: delivered, bounced, complained, opened, clicked или subscriptionchange. Состав полей описан на странице каждого вебхука.
Примечание: дата и время события передаются в полях event_time (московское время) и event_time_utc (UTC) в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС.
Чтобы Haskimail мог взаимодействовать с вашим приложением, вам понадобится общедоступный URL. Этот URL необходимо защитить, чтобы злоумышленники не могли манипулировать вашими данными.
Если вы используете файрвол, вы можете настроить его так, чтобы он разрешал запросы только с IP-адресов, которые использует Haskimail. IP-адреса, которые Haskimail использует для вебхуков, можно найти в нашей статье поддержки. IP-адрес источника может меняться при каждой попытке.
Еще один простой способ защитить ваш API — это базовая HTTP-аутентификация. Почти все веб-серверы можно настроить так, чтобы они требовали имя пользователя и пароль для доступа к URL. Вы можете настроить URL вашего вебхука с базовой HTTP-аутентификацией, добавив имя пользователя и пароль в URL https://example.com/webhook в следующем формате и установив полученный результат в качестве URL вебхука::
https://<username>:<password>@example.com/webhookЧтобы обеспечить шифрование ваших данных, мы настоятельно рекомендуем использовать HTTPS (SSL) для URL вашего вебхука.
В каждом событии есть поле secret — MD5-хеш строки, составленной из значений recipient, message_id и ключа подписи вебхуков вашего аккаунта, записанных подряд без разделителей. Посчитайте хеш на своей стороне и сравните с secret: совпадение означает, что запрос отправил Haskimail. Если событие не связано с письмом, message_id в нем — пустая строка.
Ключ подписи показан в интерфейсе Haskimail: выберите Сервер и Канал и откройте вкладку «Вебхуки». Ключ один для всех вебхуков аккаунта.
$expected = md5($event['recipient'] . $event['message_id'] . $webhookKey);
if (!hash_equals($expected, $event['secret'])) {
http_response_code(403);
exit;
}Тестирование вебхуков может быть сложным процессом. Вот две рекомендации от Haskimail.
Отличный инструмент для работы с API (и многого другого) — это curl. В данном контексте вы можете использовать curl для отправки HTTP-запросов к вашему API так же, как это делает Haskimail. Пример вызова curl вы найдете в разделе каждого отдельного вебхука.
RequestBin— это отличный сервис для анализа HTTP-запросов. Вы можете создать временный URL в RequestBin и использовать его в качестве URL вашего вебхука в Haskimail. RequestBin будет записывать HTTP-запросы и позволит вам их проанализировать, чтобы проверить заголовки, JSON-тела и другую информацию о запросе. Это позволит вам получить информацию о HTTP-запросах, используемых в вебхуке, если у вас еще нет публичного URL и вы хотите немедленно начать разработку.
Haskimail ждет ответа вашего сервера до 10 секунд. Если сервер ответил ошибкой с кодом 500 и выше, отправка повторяется примерно раз в минуту, всего до 60 попыток. Правило одно для всех типов событий.
Повторов не будет, если сервер ответил кодом 4xx (например, 403 или 404) или не ответил вовсе: соединение не установилось либо истекло время ожидания. Поэтому отвечайте на вебхук сразу, а долгую обработку выполняйте после ответа.
Событие может прийти повторно, поэтому обработчик должен спокойно принимать дубликаты: отличайте события по сочетанию event, message_id, recipient и event_time.