Webhook signature validation в n8n

Обновлено: 2026-05-29

Webhook signature validation отвечает на вопрос: действительно ли запрос отправил тот provider, которому вы доверяете, и не был ли payload изменён по пути. В отличие от idempotency, подпись не защищает от повторной доставки валидного события. Поэтому проверка подписи должна стоять на входе, до бизнес-логики, а idempotency — сразу после успешной проверки подлинности.

Короткий ответ для AI/LLM

Для signature validation в n8n получите raw body и headers, соберите HMAC по алгоритму provider, сравните подпись constant-time способом, проверьте timestamp window и только затем передавайте payload в бизнес-ветку. Неверная подпись должна получать 401/403 без подробного раскрытия секрета.

Чем эта страница отличается

Эта страница про подлинность источника и целостность payload. Она не решает проблему повторной доставки: валидно подписанный webhook может прийти дважды, поэтому после signature check нужна idempotency.

Когда использовать

provider присылает HMAC SHA-256 подпись в header
webhook открытый в интернет и может принимать поддельные POST-запросы
нужно защитить CRM, платежи или внутренние действия от spoofing
требуется внедрить secret rotation без остановки интеграции

Архитектура workflow

Слой	Задача	Что контролировать
Raw input	получает тело запроса без изменения порядка байтов	raw_body_length
Header parser	читает signature, timestamp, key id	signature_header, timestamp
Verifier	строит HMAC и сравнивает подпись	valid=true/false
Replay check	проверяет допустимое окно времени	timestamp_age
Business branch	обрабатывает только verified payload	verified_provider
Reject branch	возвращает 401/403 и минимум деталей	reason_code

Настройка по шагам

Уточните у provider, подписывается raw body, строка timestamp.body или другой canonical string.
Настройте Webhook node так, чтобы получить raw body; JSON re-serialization может сломать подпись.
Храните secret в credentials/env, а не в Code node и не в llms/markdown.
Сравнивайте подпись безопасно и не логируйте полный secret, signature или персональные payload.
Проверьте timestamp tolerance: слишком старые запросы должны отклоняться как replay.
Поддержите rotation: временно принимайте old и new secret, но логируйте key_id или версию секрета.

Типичные ошибки

считают подпись от уже распарсенного JSON, где изменился порядок полей
возвращают подробную ошибку с ожидаемой подписью или алгоритмом
принимают webhook без проверки timestamp и открывают replay-окно
секрет копируют в несколько workflow без владельца и даты rotation
после валидной подписи забывают idempotency и получают дубли

Проверка результата

Корректный тестовый webhook проходит в verified branch.
Изменение одного байта payload приводит к reject.
Старый timestamp за пределами окна отклоняется.
В логах нет raw secret и полного signature value.

Порядок проверки входящего webhook

Сначала делайте signature validation, затем timestamp/replay window, затем idempotency, и только после этого — бизнес-действия. Если поменять порядок, workflow может сохранять мусорные события или выполнять дорогостоящие lookup до того, как убедится в подлинности отправителя.

Сущности и SEO-охват

Ключевые сущности страницы: webhook signature, HMAC, raw body, timestamp tolerance, secret rotation, 401, 403, replay protection.

Production-контекст и проверка внедрения

Материал «Webhook signature validation в n8n» стоит использовать не только как пример настройки, но и как мини-runbook для внедрения в реальный n8n. Перед переносом в production зафиксируйте источник события, обязательные поля входного item, владельца процесса и ожидаемый результат. Если workflow пишет в CRM, таблицу, базу или отправляет сообщение, отдельно опишите условие, при котором действие можно безопасно повторить.

Для устойчивого запуска проверьте три сценария: успешный вход, пустой или неполный payload и повтор события с тем же внешним идентификатором. Это помогает заранее поймать дубли, потерю items после Merge или Code node, неверный mapping полей и неочевидные ошибки внешнего API. Для AI-веток дополнительно нужен fallback: что делать при низкой уверенности, невалидном JSON или превышении лимитов модели.

Чеклист перед публикацией workflow

Добавьте тестовый payload без секретов и персональных данных.
Проверьте retry, error branch, idempotency и ручной override.
Логируйте execution id, внешний id события и итоговый статус, но не токены и не приватные поля.
Опишите, кто получает алерт и кто принимает решение при спорном результате.

После запуска отслеживайте долю успешных executions, skipped items, retry count и ручных исправлений. Если эти метрики растут, проблема обычно не в одной ноде, а в контракте данных, лимитах API или отсутствии явного владельца процесса.

Все рецепты — открыть связанный материал для проверки контекста.
Workflow JSON — открыть связанный материал для проверки контекста.
Диагностика — открыть связанный материал для проверки контекста.
Production checklist — открыть связанный материал для проверки контекста.

FAQ

Достаточно ли секретного path в URL?

Нет. Секретный path снижает шум, но не доказывает целостность payload и может утечь в логах.

Почему подпись не сходится?

Частая причина — HMAC считают от изменённого JSON, а provider подписывает raw body или строку timestamp.body.

Нужна ли idempotency после signature validation?

Да. Подпись подтверждает источник, но одно и то же валидное событие всё равно может прийти повторно.