Вебхуки

Подключение обработчика

Подготовьте публичный HTTPS-адрес на порту 443 с действительным сертификатом.
В «Интеграции» → «Вебхуки» выберите ящик, события и папки. Подтвердите создание паролем владельца.
Сохраните выданный секрет whsec_... в настройках backend. Он показывается один раз.
Нажмите «Подтвердить адрес». Проверка отправится в очередь отдельного обработчика.
Верните challenge и обновите список: вебхук станет активным после успешной проверки.

До 2 вебхуков на ящик. В кабинете состояние проверки ограниченно обновляется автоматически; результат также можно получить кнопкой «Обновить».

Подтверждение адреса

Плима отправляет POST с JSON:

{"type":"webhook.verification","challenge":"CHALLENGE_VALUE"}

Обработчик должен вернуть 2xx, Content-Type: application/json и тот же challenge:

{"challenge":"CHALLENGE_VALUE"}

Перенаправления запрещены. Localhost, частные, служебные адреса и внутренние IPv6 недоступны. DNS повторно проверяется при соединении. При смене адреса создайте и подтвердите новый вебхук; старую очередь нельзя перенаправить на другой сайт.

События

message.created: Появилось новое письмо, включая импорт. Это не обязательно поступление по SMTP.
message.updated: Изменились флаги или папки существующего письма.
message.deleted: Письмо окончательно удалено.
webhook.test: Искусственное проверочное событие по кнопке в кабинете.

{
  "id": "evt_EXAMPLE",
  "type": "message.created",
  "version": 1,
  "occurredAt": "2026-11-04T09:30:00Z",
  "data": {
    "mailboxId": "MAILBOX_ID",
    "messageId": "MESSAGE_ID",
    "folderIds": ["FOLDER_ID"]
  }
}

По умолчанию выбрана папка «Входящие». Можно включить все папки, включая спам. Перемещение существующего письма во входящие является изменением, а не новым письмом. Изменение, выводящее письмо из выбранной папки, также передаётся для сверки состояния.

У message.deleted папки могут быть неизвестны, если письмо раньше не отслеживалось. Такое удаление передаётся подпискам с выбранным событием удаления независимо от фильтра папки. Не считайте отсутствие folderIds доказательством, что письмо было во входящих.

Событие содержит метаданные. Тему, текст и вложения запрашивайте через API чтения с отдельным ключом. Секрет подписи не является API-ключом.

Проверка подписи

Webhook-Id: evt_EXAMPLE
Webhook-Timestamp: 1793784600
Webhook-Signature: v1=HEX_HMAC_SHA256

Подписывается строка timestamp + "." + rawBody алгоритмом HMAC-SHA256 с вашим секретом whsec_.... Используйте исходные байты тела до JSON-разбора. Повторная сериализация JSON изменяет подпись.

Проверьте время с допустимым отклонением не больше 5 минут, сравните подпись за постоянное время и убедитесь, что Webhook-Id совпадает с id события. Пример проверки для Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';

function validSignature(rawBody, headers, secret) {
  const stamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];
  if (!/^\d+$/.test(stamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(stamp)) > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/i.test(signature || '')) return false;

  const expected = createHmac('sha256', secret)
    .update(stamp + '.')
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature.slice(3), 'hex');
  return received.length === expected.length &&
    timingSafeEqual(received, expected);
}

В примере rawBody является Buffer, заголовки нормализованы в нижний регистр, секрет берётся из защищённого серверного окружения. Ограничьте размер входящего запроса. Сначала проверьте подпись, затем разбирайте JSON.

Повторы и надёжность

Успешный приём: любой 2xx. Отвечайте после надёжного сохранения события в своей очереди.
Сетевые ошибки, 408, 429 и 5xx: повторы с увеличением интервала от 10 секунд до 15 минут и случайным разбросом.
Другие ошибки завершают доставку; 410 приостанавливает вебхук.
Срок доставки: до 24 часов. Доступны журнал и ручной повтор.
Одно событие может прийти несколько раз. Устраняйте дубли по event.id в постоянной базе.
При повторе сохраняется event.id, но timestamp и подпись новые.

Проверка изменений выполняется примерно каждые 5 секунд с ограничением нагрузки. Это не гарантия доставки за определённое число секунд.

Журнал и управление

Журнал попыток хранится 30 дней: тип, идентификаторы, время, HTTP-результат и ошибка. Тела писем и секреты в нём не хранятся. История метаданных /v1/events доступна 7 дней при активных вебхуках. Как читать историю.

В кабинете можно приостановить доставку, возобновить подтверждённый адрес, отправить проверочное событие, повторить неудачную доставку, заменить секрет и удалить вебхук. Эти действия требуют пароль владельца.

После замены секрета сразу используется новое значение, автоматического периода перекрытия нет. Обновите обработчик. Если нужно принять уже отправленные запросы со старой подписью, на своей стороне кратковременно поддержите оба секрета с явным сроком удаления старого.