Webhook валидации email: автоматические уведомления о результатах проверки

Webhook валидации email - это HTTP-запрос, который сервис проверки автоматически отправляет на ваш сервер, когда верификация адреса или списка адресов завершена. Вы указываете callback URL заранее. Сервис выполняет проверку, формирует JSON с результатами и отправляет его POST-запросом на этот URL. Ваш сервер принимает данные и обрабатывает их: обновляет CRM, блокирует невалидный контакт, запускает следующий шаг автоматизации. Вся цепочка работает без ручного участия.

Такая модель называется push-доставкой. Противоположность - polling (pull-модель), где ваше приложение периодически спрашивает API: «готово?». Webhook устраняет и задержку между завершением проверки и получением результата, и лишнюю нагрузку от повторяющихся запросов.

Как работает webhook при валидации

Процесс состоит из четырёх шагов. Первый: вы регистрируете callback URL в настройках сервиса валидации. Это endpoint на вашем сервере, который принимает POST-запросы. Второй: ваше приложение отправляет email (или список) на проверку через API и получает идентификатор задачи. Третий: сервис валидации выполняет все этапы проверки - синтаксис, DNS, MX-запись, SMTP-подключение, определение одноразовых почт и ролевых адресов. Четвёртый: по завершении сервис отправляет POST-запрос на ваш callback URL с телом в формате JSON. Тело содержит ID задачи и результаты.

Ваш сервер сопоставляет ID задачи с исходным запросом и выполняет действие. Для единичной проверки - обновляет статус контакта. Для пакетной - скачивает файл результатов по ссылке из webhook-запроса или обрабатывает агрегированную статистику.

Зачем нужен webhook, если есть синхронный API

Синхронный API работает для единичных проверок: отправили адрес, подождали 2-5 секунд, получили ответ. Для формы регистрации это приемлемо. Но при пакетной проверке списка на десятки тысяч адресов синхронное ожидание невозможно. Проверка занимает от нескольких минут до нескольких часов в зависимости от размера списка и количества уникальных доменов.

Без webhook вам остаётся polling: каждые 30-60 секунд отправляете запрос к API со статусом задачи. Это создаёт постоянную нагрузку на оба сервера и вносит задержку: если проверка завершилась через секунду после вашего очередного опроса, вы узнаете об этом только через 29 секунд. Webhook устраняет обе проблемы. Нет лишних запросов, нет задержки.

Webhook полезен и при единичной проверке в фоновом режиме. Пользователь заполняет форму подписки, вы принимаете адрес и отправляете его на проверку асинхронно. Пользователь получает подтверждение подписки сразу, без ожидания. Когда webhook приходит с результатом, ваш бэкенд обновляет статус контакта. Если адрес оказался невалидным - помечаете запись и не включаете её в следующую рассылку.

Что содержит webhook-запрос

Для единичной проверки тело запроса обычно включает: проверяемый email-адрес, статус валидации (valid, invalid, risky, unknown), причину статуса, набор флагов (is_disposable, is_role, is_catch_all, is_free) и числовой score качества адреса. По сути, вы получаете тот же ответ, что вернул бы синхронный API, только доставленный к вам, а не запрошенный вами.

Для пакетных проверок структура другая. Передавать результаты по всем 50 000 адресам в теле одного POST-запроса непрактично. Поэтому webhook содержит ID задачи, общую статистику (количество valid, invalid, risky, unknown), время завершения и ссылку для скачивания полного файла результатов в формате CSV или JSON. Ваш сервер, получив webhook, скачивает файл и обрабатывает его.

Безопасность webhook-endpoint

Callback URL - это открытая дверь в вашу систему. Если endpoint не защищён, любой может отправить на него фейковый запрос и подменить результаты проверки. Адрес, который на самом деле невалиден, будет помечен как рабочий. Или наоборот - рабочий адрес клиента попадёт в блокировку. Защита обязательна.

HMAC-подпись. Наиболее надёжный метод. Сервис валидации подписывает тело запроса секретным ключом, который знаете только вы и сервис. Подпись передается в HTTP-заголовке. Ваш сервер вычисляет подпись по тому же алгоритму и сравнивает. Не совпадает - запрос отклоняется. Подделать подпись без знания ключа невозможно.

Секрет в URL. Более простой вариант: добавляете случайную строку в callback URL, например /webhook/validate/a8f3e2b1c9d0. Этот URL знают только вы и сервис валидации. Менее надёжно, чем HMAC - URL может утечь через логи, referer или панель администратора. Но для базовой защиты достаточно.

Фильтрация по IP. Принимаете запросы только с IP-адресов, принадлежащих сервису валидации. Работает, пока сервис не сменит инфраструктуру. Не используйте как единственный метод защиты.

HTTPS. Не метод аутентификации, но обязательное условие. Webhook передаёт email-адреса - персональные данные по смыслу GDPR. Открытый HTTP означает, что любой посредник может прочитать содержимое. Все callback URL должны начинаться с https://.

Обработка ошибок, retry и идемпотентность

Ваш сервер может оказаться недоступен в момент webhook-запроса: деплой, перезагрузка, сбой хостинга, сетевой тайм-аут. Надёжные сервисы валидации реализуют retry с нарастающими интервалами: первая повторная попытка через 1 минуту, вторая через 5, третья через 30, четвёртая через 2 часа. Если после всех попыток endpoint не ответил - задача помечается как неотправленная, и вы можете запросить повтор вручную.

Со стороны вашего endpoint важно соблюдать два правила. Первое: возвращайте HTTP 200 только после успешной обработки данных. Если вы приняли webhook, но не смогли записать результат в базу данных - верните 500. Сервис повторит попытку, и при следующей попытке ваша база, возможно, уже будет доступна. Если вернёте 200 преждевременно, данные потеряются без retry.

Второе: обеспечьте идемпотентность. Retry-логика означает, что один и тот же webhook может прийти дважды - первый запрос дошёл, ваш сервер обработал его, но ответ не дошёл обратно (тайм-аут на стороне отправителя). Сервис считает, что доставка не удалась, и отправляет повтор. Ваш endpoint не должен дублировать обработку. Проверяйте ID задачи: если результат с таким ID уже записан, верните 200 без повторного действия.

Практические сценарии использования

Пакетная очистка базы перед рассылкой. Маркетолог загружает список на проверку. Вместо того чтобы ждать на странице сервиса, он закрывает вкладку и занимается другими задачами. Когда проверка завершается, webhook отправляет уведомление на сервер компании, который автоматически обновляет статусы контактов в CRM и отправляет менеджеру сообщение в Slack или email.

Асинхронная проверка при регистрации. Пользователь создаёт аккаунт. Бэкенд принимает email, отправляет его на валидацию в фоне и создаёт аккаунт со статусом «email не подтверждён». Через несколько секунд приходит webhook. Если адрес валиден - статус меняется. Если нет - пользователю отправляется уведомление с просьбой указать другой адрес.

Конвейерная обработка данных. В системах, где данные поступают непрерывно (формы лидогенерации, импорт из партнёрских систем), webhook встраивается в pipeline. Новый контакт поступает, отправляется на проверку, результат приходит по webhook и определяет дальнейший маршрут: валидный адрес идёт в активную базу, невалидный - в карантин, рискованный - на дополнительную верификацию.

Webhook против polling: сравнение по нагрузке

Предположим, пакетная проверка 100 000 адресов занимает 45 минут. При polling с интервалом 30 секунд ваш сервер отправит 90 запросов на проверку статуса. Из них 89 получат ответ «ещё обрабатывается», и только последний вернёт результат. С webhook вместо 90 запросов будет один входящий POST.

При масштабировании разница становится критической. Если вы запускаете 10 пакетных проверок в день, polling генерирует около 900 запросов, webhook - 10 входящих. При 100 проверках в день: 9 000 против 100. Меньше трафика, меньше нагрузка на API, меньше потребление ресурсов на вашем сервере.