техническое · ответ с источниками

Email-вебхуки: что это и как их реализовать

Email-вебхук — HTTP-обратный вызов, который почтовый сервис инициирует, чтобы уведомить целевой сервер о конкретных событиях. Вместо того чтобы приложение опрашивало API в ожидании обновлений статуса, провайдер сразу после события — например, сбоя доставки или клика по ссылке — отправляет полезную нагрузку (payload) в формате JSON или XML на заранее заданный URL.

Как это работает

Когда происходит событие, почтовый провайдер формирует HTTP-запрос POST. Он содержит полезную нагрузку с метаданными события, включая ID письма, адрес получателя и временную метку. Принимающий сервер должен слушать публичный эндпоинт, проверять входящий запрос и возвращать ответ 200 OK, подтверждая получение. Если сервер возвращает ошибку, провайдер может повторить доставку, используя стратегию экспоненциальной задержки (exponential backoff).

Почему это важно для отправителей

Вебхуки критически важны для поддержания репутации отправителя. Получая уведомления о жёстких отказах или жалобах на спам в реальном времени, разработчики могут автоматически удалять недействительные адреса из своих списков. Это предотвращает повторную отправку на несуществующие почтовые ящики — один из основных сигналов, по которым интернет-провайдеры помечают отправителей как некачественных. Быстрая реакция на такие сигналы обеспечивает более высокую общую доставляемость.

Что учесть в эксплуатации

Типичные сбои — ошибки тайм-аута, когда принимающий сервер обрабатывает полезную нагрузку синхронно. Чтобы их избежать, разработчикам стоит строить асинхронную архитектуру: вебхук принимается, ставится в очередь в системе вроде Redis или RabbitMQ и сразу подтверждается. Кроме того, первостепенное значение имеет безопасность: серверы должны проверять подпись провайдера или IP-адрес источника, чтобы не принимать поддельные уведомления о событиях.

Конкретный пример реализации

Типичный сценарий — настройка URL у провайдера вроде Resend или Amazon SES. Когда пользователь кликает по ссылке в письме, провайдер отправляет POST-запрос на /webhooks/email с телом вида { event: click, email: user@example.com, link: https://site.com/offer }. Затем приложение обновляет запись пользователя в базе данных, отмечая кампанию как успешную.

Интеграция с инструментами

Для настройки вебхуков нужен публичный URL и способ тестировать полезные нагрузки. SendHQ и его бесплатные инструменты (https://sendhq.cc/tools) помогают разработчикам выполнять технические требования к почтовой инфраструктуре и приводить конфигурацию в соответствие с отраслевыми стандартами.

Что спрашивают команды

Чем API отличается от вебхука?

API — это запрос, который клиент отправляет серверу, чтобы получить данные. Вебхук — это запрос, который сервер отправляет клиенту, чтобы автоматически передать данные, когда происходит событие.

Как защитить эндпоинт email-вебхука?

Используйте секретные токены в заголовке, проверяйте HMAC-подпись, которую предоставляет почтовый сервис, или ограничьте входящий трафик диапазонами IP-адресов, принадлежащими провайдеру.

Что будет, если во время события вебхука мой сервер недоступен?

Большинство профессиональных провайдеров ставят событие в очередь и несколько раз пытаются доставить его повторно в течение нескольких часов или дней, прежде чем пометить как недоставляемое.

Первоисточники

Документация Resend — Resend
Документация для разработчиков Postmark — Postmark
Руководство разработчика Amazon SES — Amazon Web Services