Вебхуки: события, подписи и повторы

События

Каждый эндпоинт подписывается на 1–20 типов событий:

• email.accepted
• email.queued
• email.sent
• email.delivered
• email.deferred
• email.bounced
• email.complained
• email.opened
• email.clicked
• email.received
• email.suppressed
• domain.verified
• domain.failed

Данные для подписи

HMAC-SHA256(secret, timestamp + "\0" + event_id + "\0" + body)

Postline-Timestamp: 1784743200
Postline-Event-Id: evt_…
Postline-Signature: v1=…

Запрос и тело события

POST https://example.com/hooks/postline
Content-Type: application/json
Postline-Event-Id: evt_3f2a9c…
Postline-Timestamp: 1784743200
Postline-Signature: v1=5d41402abc4b2a76…

{
  "id": "evt_3f2a9c…",
  "type": "email.delivered",
  "created_at": "2026-11-05T12:00:00Z",
  "data": {
    "email_id": "msg_01J…",
    "recipient": "user@example.net",
    "provider": "gmail",
    "smtp_response": "250 2.0.0 OK"
  }
}

Требования к получателю

• Считайте подпись из точного «сырого» тела запроса.
• Сравнивайте подписи constant-time.
• Отклоняйте timestamp вне допустимого окна.
• Сохраняйте event_id и обрабатывайте каждое событие один раз.
• Не считайте, что события приходят в порядке жизненного цикла.

Исходящие ограничения

Создание эндпоинта требует HTTPS. Приватные, loopback, link-local, metadata-адреса и адреса с учётными данными блокируются и повторно резолвятся в момент подключения. Редиректы не выполняются. Доставка использует ограниченные таймауты и число попыток.

Таймауты и повторы

Любой ответ 2xx подтверждает событие. Таймаут (15 с), сетевая ошибка или другой статус считаются неудачей. Postline делает до 6 попыток: первую и повторы через 1 мин, 5 мин, 30 мин, 2 ч и 8 ч. Каждая попытка сохраняется в журнале доставок, любую доставку можно повторить вручную через API или панель.