События и вебхуки
Подключение вебхуков
Укажите адрес для получения вебхуков в настройках вашей интеграции. На него будут приходить уведомления о новых письмах, состоянии ящиков и результатах операций.
В настройках интеграции задайте отдельный секрет вебхуков и включите доставку. Этот секрет используется для проверки подписи уведомлений; почтовый API-ключ для этого не подходит.
Формат уведомления
Уведомление приходит HTTP POST-запросом с Content-Type: application/json. Поле event содержит тип события, timestamp — время уведомления, data — данные события. Состав data зависит от события.
Идентификатор data.event_id позволяет распознать повторную доставку. Сохраняйте его вместе с идентификатором вашей интеграции и обрабатывайте одно событие только один раз.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}Проверка и подтверждение
Заголовок X-Webhook-Signature содержит HMAC-SHA256 в шестнадцатеричной записи нижнего регистра. Рассчитайте подпись по исходным байтам тела запроса и секрету вебхуков. Проверяйте подпись до обработки данных; повторная сериализация JSON изменит подписываемые байты.
После проверки подписи и сохранения события верните HTTP 200 или 201. Ответы 202 и 204 не подтверждают получение. Ответьте в течение 10 секунд; длительную обработку выполните после сохранения события.
Уведомления могут приходить повторно и не по порядку. Перед изменением состояния подписки сверяйте её текущие данные. История доставки доступна в настройках интеграции.
Какие события возникают
mailbox.created- Ящик создан и готов к использованию.
mailbox.expiring- Приближается окончание оплаченного срока ящика.
mailbox.renewed- Оплаченный срок ящика продлён.
mailbox.suspended- Доступ к ящику приостановлен: чтение и отправка недоступны.
mailbox.resumed- Доступ к ящику восстановлен.
mailbox.deleting_soon- До удаления неоплаченного ящика остался один час.
mailbox.deleted- Ящик удалён.
mailbox.account_changed- Ящик привязан к другому почтовому аккаунту.
mail.message.received- В ящике появилось новое входящее письмо.
mail.operation.succeeded- Операция завершилась успешно. Для отправки это означает принятие письма почтовым сервером, а не доставку во входящие получателя.
mail.operation.failed- Операция завершилась ошибкой.
mail.operation.uncertain- Результат отправки неизвестен. Проверьте состояние перед повторной отправкой.
Напоминания об оплате: за 14, 7, 3, 2, 1 день и за час до истечения. Продление отменяет ещё не отправленные устаревшие напоминания.