Webhook-запити

Коли відбувається подія, Emailit надсилає HTTP POST запит на налаштовану URL-адресу вашого webhook’а. На цій сторінці описано формат запиту, заголовки та поведінку доставки.

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

Усі webhook-запити надсилаються як POST запити з JSON-тілом:

Метод: POST
Content-Type: application/json
Таймаут: 30 секунд

Заголовки

Кожен webhook-запит містить наступні заголовки:

Заголовок	Опис
`Content-Type`	`application/json`
`User-Agent`	`Emailit-Webhooks/2.0`
`X-Emailit-Signature`	HMAC-SHA256 підпис для перевірки автентичності
`X-Emailit-Timestamp`	Unix-мітка часу підписання запиту

Тіло запиту

Тіло запиту містить дані події у форматі JSON:

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

Очікувана відповідь

Ваша кінцева точка повинна повернути статус-код 2xx (наприклад, 200, 201, 204) для підтвердження отримання. Будь-який інший статус-код розглядається як помилка.

Політика повторних спроб

Якщо ваша кінцева точка не відповідає статус-кодом 2xx протягом 30 секунд, Emailit повторить доставку згідно з наступним розкладом:

Спроба	Затримка
0	5 секунд
1	5 хвилин
2	30 хвилин
3	2 години
4	5 годин
5	10 годин
6	24 години

Після спроби 6 (загалом 7 спроб) webhook автоматично відключається. Ви можете знову увімкнути його з панелі керування Emailit.

Порядок доставки

Webhook-події доставляються майже в реальному часі, але не гарантується їх доставка в правильному порядку. Використовуйте event_id та мітки часу в даних події для обробки порядку у вашому додатку.

IP-адреси

Webhook-запити надсилаються з інфраструктури Emailit. Якщо вам потрібно додати IP-адреси до білого списку, зверніться до служби підтримки за актуальним переліком вихідних IP-адрес.

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

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