Вебхук — это HTTP-запрос, который сервис отправляет вашему приложению, когда с письмом что-то происходит: оно доставлено, отклонено, отложено, открыто или получатель отписался. Так приложение узнаёт о судьбе письма, не опрашивая API.
POST с JSON на ваш URL и подписывает запрос секретом эндпоинта.2xx и обрабатывает событие.whsec_… создаётся вместе с эндпоинтом и показывается только один раз. Скопируйте его сразу и храните как пароль. | Событие | Когда приходит |
|---|---|
delivered | сервер получателя принял письмо |
deferred | временный отказ, доставка будет повторена |
bounced | постоянный отказ, доставка невозможна |
complained | получатель пожаловался на спам |
dropped | письмо не отправлено — например, адрес в списке исключений |
opened | письмо открыли |
unsubscribed | получатель отписался |
{
"event_id": "a1b2c3d4-0001-4f3a-9c2e-7b6d5e4f3a21",
"event": "delivered",
"domain": "mail.example.ru",
"domain_id": "0f2b8c14-9a3d-4e57-8b6f-2c1d0e9a7b53",
"message_id": "<2f1c8e90-9b4d-4c3a-aa10-5e7d2c1b9f01@mail.example.ru>",
"original_message_id": "<order-4417@app.example.ru>",
"email": "client@example.ru",
"tags": {},
"timestamp": "2026-06-24T09:41:13.482921+00:00",
"data": {
"smtp_code": 250,
"mx_host": "mx.example.ru"
}
}| Поле | Что содержит |
|---|---|
event_id | идентификатор события; повторная доставка приходит с тем же значением |
event | тип события из таблицы выше |
domain, domain_id | домен, с которого ушло письмо, и его идентификатор |
message_id | Message-ID, который письму присвоил сервис, — <uuid@ваш-домен>. Его же возвращает API при отправке |
original_message_id | Message-ID, который записал ваш клиент при отправке по SMTP, без изменений. Пустая строка для писем через API и для SMTP-писем без этого заголовка |
email | адрес получателя |
tags | метки из запроса к API; {}, если их нет |
timestamp | время события, UTC, ISO-8601 |
data | поля конкретного события, может быть {} |
Заголовки:
X-Webhook-Event: delivered
X-Webhook-Delivery: a1b2c3d4-0001-4f3a-9c2e-7b6d5e4f3a21
X-Webhook-Timestamp: 1782639673
X-Webhook-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08По SMTP. Сервис заменяет Message-ID письма на свой, поэтому в message_id вашего значения нет. Но оно сохраняется и приходит в каждом вебхуке как original_message_id. Задавайте уникальный Message-ID каждому письму и сопоставляйте события по паре original_message_id + email: письмо нескольким получателям становится отдельным письмом на каждого, и у всех копий original_message_id одинаковый. Найти письмо можно и через API: GET /external/emails/?original_message_id=<…>.
По API. Сохраните message_id из ответа и передавайте idempotency_key — повторный запрос с тем же ключом не создаст второе письмо.
Подпись — HMAC-SHA256 от строки {timestamp}.{тело запроса}, где тело берётся в исходном виде, до разбора JSON. Ключ — секрет эндпоинта.
import hmac
import hashlib
WEBHOOK_SECRET = "whsec_..." # секрет эндпоинта из панели
def is_valid(headers, raw_body: bytes) -> bool:
signature = headers["X-Webhook-Signature"]
timestamp = headers["X-Webhook-Timestamp"]
# 1. Отбросьте запросы со старой меткой времени — защита от повторов.
# (сравните timestamp с текущим временем, допуск в несколько минут)
# 2. Пересчитайте подпись по строке "{timestamp}.{raw_body}".
signed = f"{timestamp}.".encode() + raw_body
expected = hmac.new(
WEBHOOK_SECRET.encode(), signed, hashlib.sha256
).hexdigest()
# 3. Сравнивайте за постоянное время.
return hmac.compare_digest(expected, signature)2xx сразу, а обработку выполняйте асинхронно — долгий ответ считается неудачей.2xx, доставка повторяется; время следующей попытки видно в панели.event_id для защиты от повторной обработки.