Анонсируем Webhooks v2

Мы запускаем Webhooks v2 — полную переработку системы доставки уведомлений о событиях в реальном времени для ваших приложений в Emailit. С 36 типами событий по 9 категориям ресурсов, криптографической проверкой подписи и надёжной политикой повторных попыток, Webhooks v2 предоставляет всё необходимое для создания стабильных интеграций, управляемых событиями.

Что нового

36 типов событий по 9 ресурсам

Webhooks v2 охватывает все ресурсы в Emailit. Вы можете подписаться именно на те события, которые вас интересуют, или использовать all_events для получения всех уведомлений.

События email отслеживают полный жизненный цикл доставки:

Событие	Описание
email.accepted	Принято к доставке
email.scheduled	Запланировано для будущей доставки
email.delivered	Доставлено на почтовый сервер получателя
email.bounced	Окончательная неудача доставки (жёсткий отказ)
email.attempted	Временная неудача доставки
email.failed	Не удалось доставить из-за конкретной ошибки
email.rejected	Принято, затем отклонено
email.suppressed	Получатель находится в списке подавления
email.received	Входящее письмо было принято
email.complained	Зарегистрирована жалоба на спам
email.clicked	Была нажата ссылка в письме
email.loaded	Содержимое письма было загружено (открыто)

CRUD-события для доменов, аудиторий, подписчиков, контактов, шаблонов, подавлений, проверок email и списков проверки email — каждый с событиями .created, .updated и .deleted.

Единообразная структура событий

Каждый webhook-запрос следует одной и той же структуре, что упрощает создание единого обработчика для всех событий:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

event_id уникально идентифицирует каждое событие, type сообщает, что произошло, а data.object содержит полный ресурс на момент события.

Проверка подписи HMAC-SHA256

Каждый webhook-запрос подписывается вашим секретным ключом webhook с использованием HMAC-SHA256. Подпись вычисляется для {timestamp}.{rawBody}, поэтому вы можете проверить как подлинность, так и актуальность за один шаг.

Каждый запрос включает два заголовка:

• X-Emailit-Signature — HMAC-SHA256 hex-дайджест
• X-Emailit-Timestamp — Unix-метка времени, используемая в подписи

Мы настоятельно рекомендуем использовать безопасное по времени сравнение (например, crypto.timingSafeEqual в Node.js) для предотвращения атак по времени и отклонять запросы с метками времени старше нескольких минут для защиты от атак повторного воспроизведения.

Полные примеры проверки для Node.js, Python, PHP, Ruby и Go доступны в документации Подпись запроса.

Автоматические повторы с экспоненциальной задержкой

Если ваша конечная точка не отвечает с кодом 2xx в течение 30 секунд, Emailit автоматически повторяет попытку:

Попытка	Задержка
0	5 секунд
1	5 минут
2	30 минут
3	2 часа
4	5 часов
5	10 часов
6	24 часа

Всего 7 попыток в течение примерно 41 часа. После финальной попытки webhook автоматически отключается. Вы можете повторно включить его в панели управления в любое время.

Формат запроса

Все webhook-запросы используют метод POST с JSON-телом. Каждый запрос включает следующие заголовки:

Заголовок	Описание
Content-Type	application/json
User-Agent	Emailit-Webhook/1.0
X-Emailit-Signature	HMAC-SHA256 подпись
X-Emailit-Timestamp	Unix-метка времени, используемая в подписи

Лучшие практики

• Отвечайте быстро — Возвращайте 2xx немедленно и обрабатывайте данные асинхронно в фоновой задаче.
• Обрабатывайте дубликаты — Одно и то же событие может быть доставлено несколько раз при повторных попытках. Используйте event_id для дедупликации.
• Проверяйте подписи — Всегда валидируйте заголовок X-Emailit-Signature, чтобы подтвердить, что запрос пришёл от Emailit.
• Защищайтесь от атак повторного воспроизведения — Проверяйте X-Emailit-Timestamp и отклоняйте запросы старше нескольких минут.

Полная документация

Мы опубликовали полную документацию для Webhooks v2 с подробными примерами данных и описанием полей для всех 36 событий:

• Введение — Обзор и принципы работы webhooks
• Типы событий — Полный список всех 36 типов событий
• Webhook-запросы — Формат запроса, заголовки и политика повторов
• Подпись запроса — Проверка подписи с примерами кода на 5 языках

Начало работы

Переходите к документации Webhooks для начала работы или сразу к справочнику API для создания вашей первой webhook-конечной точки.