Публичный webhook endpoint нельзя защищать только скрытым URL или проверкой полей JSON. Любой, кто узнает адрес, способен прислать похожее тело. До постановки события в очередь и любых изменений проверьте криптографическую подпись по правилам конкретного провайдера. Если подписи нет или она не совпала, обработка должна завершиться отказом.

Критическая деталь — считать HMAC от исходных байтов HTTP body. Если framework сначала разобрал JSON, поменял порядок ключей и затем сериализовал объект заново, подпись законного запроса не совпадёт. Сохраните raw body в middleware, но не записывайте его целиком в журналы: payload может содержать персональные данные и секретные значения.

Порядок проверок важнее количества фильтров

  1. Ограничить размер тела и принять запрос только по HTTPS.
  2. Получить raw body и заголовок подписи без преобразования данных.
  3. Вычислить ожидаемый MAC с актуальным секретом и требуемым алгоритмом.
  4. Сравнить значения constant-time функцией и отклонить несовпадение.
  5. Проверить тип события, delivery ID и допустимость повтора.
  6. Быстро вернуть успешный ответ и выполнить тяжёлую работу идемпотентно в очереди.

IP allow list может быть дополнительным барьером, но не заменяет подпись: адреса провайдера меняются, а запрос способен проходить через промежуточную сеть. Для GitHub список IP получают через официальный meta endpoint и регулярно обновляют. Основным доказательством целостности остаётся секретная HMAC-подпись.

Пример для заголовка GitHub

function verifyGitHubWebhook(rawBody, header, secret) {
  if (!header || !header.startsWith('sha256=')) return false;

  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  const receivedBytes = Buffer.from(header, 'utf8');
  const expectedBytes = Buffer.from(expected, 'utf8');
  if (receivedBytes.length !== expectedBytes.length) return false;

  return crypto.timingSafeEqual(receivedBytes, expectedBytes);
}

У GitHub подпись приходит в `X-Hub-Signature-256`; старый SHA-1 заголовок не следует выбирать для новой реализации. Для другого поставщика не копируйте имена заголовков и формат вслепую: алгоритм, кодирование, timestamp и строка для подписи являются частью его контракта. Используйте официальный SDK, если он проверяет именно необработанное тело и актуальную схему.

Почему правильная подпись не останавливает replay

Перехваченный законный запрос сохраняет корректную подпись. Нужен отдельный механизм свежести или уникальности. GitHub рекомендует использовать `X-GitHub-Delivery`: повторная доставка сохраняет тот же идентификатор. Сохраните delivery ID с итоговым статусом и сделайте повтор безопасным, а не просто считайте каждую доставку новым событием.

ЗащитаОт чего помогаетЧего не решает
Секретный URLСнижает случайный шумНе доказывает источник после утечки
HMAC-подписьПодделка и изменение телаПовтор уже подписанного события
Delivery IDПовторная обработка одной доставкиПодделка без проверки подписи
Timestamp и окноСильно запоздавший replayДубликаты внутри окна без idempotency
IP allow listЧасть постороннего трафикаЦелостность payload и смена адресов

Секрет должен переживать ротацию без окна доверия

Храните webhook secret в менеджере секретов или защищённой конфигурации, а не в репозитории и не в query string. Для ротации предусмотрите короткий период проверки двумя секретами, если провайдер не переключает их атомарно. Логируйте, какой ключевой идентификатор сработал, но никогда не сам секрет или вычисленный материал, пригодный для атаки.

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

Тесты должны включать неприятные варианты

  • Корректное тело и подпись проходят один раз.
  • Изменение одного байта body даёт отказ до бизнес-логики.
  • Отсутствующий и обрезанный заголовок не приводят к исключению сервера.
  • Повтор того же delivery ID не создаёт второе действие.
  • Большое тело отсекается до дорогого вычисления и JSON-парсинга.
  • Законная redelivery возвращает согласованный ответ и видит прежний результат.

В production-метриках разделяйте invalid signature, duplicate delivery, unsupported event и внутреннюю ошибку. Резкий рост неверных подписей — повод проверить утечку URL или сканирование, но в логах достаточно хеша delivery ID, типа события и причины отказа. Сам payload и заголовки авторизации там лишние.

Проверенные источники