Анонсуємо Webhooks v2

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

Що нового

36 типів подій у 9 ресурсах

Webhooks v2 охоплює кожен ресурс в Emailit. Ви можете підписатися саме на ті події, які вас цікавлять, або використати all_events, щоб отримувати все.

Події електронної пошти відстежують повний життєвий цикл доставки:

CRUD події для доменів, аудиторій, підписників, контактів, шаблонів, придушень, перевірок електронної пошти та списків перевірки електронної пошти, кожна з подіями .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 автоматично повторює спробу:

Це 7 спроб загалом протягом приблизно 41 години. Після останньої спроби webhook автоматично вимикається. Ви можете повторно увімкнути його з панелі керування в будь-який час.

Формат запиту

Усі webhook-запити є POST з JSON-тілом. Кожен запит містить ці заголовки:

Найкращі практики

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

Повна документація

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

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

Почніть роботу

Перейдіть до документації Webhooks, щоб почати, або одразу до довідника API, щоб створити вашу першу webhook-кінцеву точку.