Подпись вебхука: проверить источник до изменения данных CRM

Доставка выглядит правильным JSON, но источник не подтверждён — и приёмник меняет данные CRM. Разбираем, как проверять подпись по сырым байтам и не путать её с защитой от повторов.

Подпись вебхука — это HMAC от исходных байтов тела запроса, который приёмник сравнивает с заголовком отправителя до разбора JSON и до записи в CRM. Проверка подтверждает отправителя и целостность, но не полномочия и не свежесть: нужны отдельные правила авторизации, окно времени и защита от повторной обработки.

Представьте условную сцену: интегратор настроил приём заявок с сайта в CRM. В логах — аккуратный JSON с именем, телефоном и суммой заказа. Менеджер открывает карточку и видит лид, которого не было. Никто не взламывал сервер и не подбирал пароль. Просто кто-то узнал адрес приёмника и отправил туда свой JSON — сервер принял его как родной, потому что не спросил, откуда пришло сообщение.

Вебхук — это входящий HTTP-запрос, который внешняя система шлёт вашему приёмнику при событии: оплата прошла, заявка создана, статус изменился. Приёмник обычно меняет данные в CRM, поэтому каждый такой запрос — это право записи, выданное внешнему миру. Подпись вебхука — способ убедиться, что запрос собрал именно тот отправитель, с которым вы договаривались, и что тело запроса не изменили по дороге. Дальше разберём, как эту проверку устроить так, чтобы она не превратилась в формальность «подпись есть — значит, всё хорошо».

Что именно подписывается: сырые байты, а не пересобранный JSON

Самая частая ошибка живёт в одной строке кода. Приёмник читает тело запроса, разбирает его в объект, потом заново сериализует и считает подпись от результата. Кажется, что это то же самое. На деле нет: порядок ключей, пробелы, экранирование юникода и формат чисел при повторной сборке могут отличаться от исходных байтов. Подпись, посчитанная от «пересобранного» тела, не совпадёт с той, что прислал отправитель, даже если данные идентичны. Хуже того — иногда совпадёт случайно, и тогда вы поверите в проверку, которой на самом деле нет.

Правило простое: сохраните тело запроса как есть, в виде байтов, до любого разбора, и считайте HMAC именно от этих байтов. Разбирайте JSON уже после успешной проверки. Это же требование лежит в основе контрактов крупных провайдеров: например, документация GitHub по проверке доставок вебхуков прямо строится вокруг вычисления подписи от исходного тела запроса и сравнения с заголовком, который прислал отправитель (GitHub: Validating webhook deliveries).

Сам примитив HMAC на основе SHA-256 в веб-платформе доступен через SubtleCrypto.sign с алгоритмом HMAC; на вход функции подаётся буфер байтов, а не объект (MDN: SubtleCrypto sign). Это не деталь реализации, а суть: подпись живёт на уровне байтов, а не на уровне «понятий», в которые вы их превратили.

Отдельно про сравнение. Подпись, пришедшую в заголовке, нельзя сравнивать обычным == в большинстве языков: такое сравнение может выходить из функции на первом несовпавшем символе и тем самым подсказывать атакующему, сколько символов уже угадано. Нужно сравнение с постоянным временем — тайм-константное. Это не паранойя ради паранойи, а стандартная гигиена аутентификации, о которой напоминает шпаргалка OWASP по аутентификации (OWASP: Authentication Cheat Sheet).

Если ваша задача — проверить защиту вебхуков, на странице соответствующего направления 404ai можно посмотреть опубликованные возможности и оставить описание текущего процесса. Конкретные подключения, исходные данные и критерии приёмки согласуем отдельно.

Эпизод первый: тело изменили, а подпись осталась прежней

Условный сценарий. Интернет-магазин шлёт в CRM событие «заказ оплачен»: номер заказа, сумма, идентификатор клиента. Приёмник проверяет подпись и, если она верна, создаёт сделку в статусе «оплачено». Однажды в логах появляется запрос с валидной подписью, но с суммой, которая не сходится с заказом, — кто-то на промежуточном узле поменял тело, а подпись осталась от исходного. Если приёмник проверяет подпись от пересобранного JSON, он этого не заметит: он ведь считает подпись от того, что получил, а не от того, что отправили.

Механизм защиты здесь такой: подпись привязана к конкретным байтам. Любое изменение тела — хоть пробела, хоть цифры в сумме — меняет вычисленный HMAC, и сравнение с заголовком проваливается. Приёмник обязан в этом случае ответить отказом и ничего не записывать. Не «записать, но пометить подозрительным», а именно не записывать: частично применённое событие хуже, чем непринятое.

Второй слой этого эпизода — что делать с отказом. Хороший приёмник не молчит и не отвечает 200 «на всякий случай». Он возвращает ошибку, пишет в лог факт отказа с идентификатором доставки (если отправитель его присылает), но не пишет в лог сам секрет и не логирует полное тело с персональными данными. Отправитель, увидев ошибку, может повторить доставку — и это уже тема повторных вебхуков, а не подписи. Здесь важно не смешивать: подпись отвечает на вопрос «кто и что прислал», повтор — на вопрос «не обработали ли мы это дважды».

Когда приёмник отвергает запрос с неверной подписью, стоит различать два случая в логах: подпись не совпала (тело изменили или секрет другой) и подпись отсутствует (пришёл вообще не тот отправитель или сломанный клиент). Это разные диагнозы, и смешивать их в одну строку «invalid signature» — значит терять информацию при разборе инцидента.

Секрет, который знают двое, и что делать, когда один из них ошибся

HMAC работает на общем секрете: отправитель и получатель знают одну строку, и подпись доказывает, что запрос собрал тот, кто эту строку знает. Отсюда два следствия. Первое: секрет — это не «настройка интеграции», а учётные данные, и обращаться с ним нужно соответственно. Второе: если секрет засветился, подпись перестаёт что-либо доказывать, пока секрет не сменят.

Условный эпизод. Разработчик при отладке скопировал секрет в личный конфиг и закоммитил его в репозиторий. Формально ничего не сломалось: доставки идут, подписи сходятся. Но теперь любой, у кого есть доступ к репозиторию, может собрать валидный запрос. Проверка подписи при этом продолжает «работать» — и это самое опасное состояние: зелёные логи при скомпрометированном ключе.

Ротация секрета — не разовое действие, а процедура. Нужно уметь принимать запросы, подписанные и старым, и новым секретом, в течение окна перехода, а потом отключить старый. Если приёмник поддерживает только один секрет, ротация превращается в простой: либо старые доставки отвергаются, либо новые. Поэтому в конфигурации приёмника полезно предусмотреть список активных секретов с меткой, а не единственное значение. Это не усложнение ради усложнения — это цена того, чтобы менять ключ без обрыва интеграции.

И ещё: секрет не должен попадать в примеры, скриншоты, тикеты поддержки и тела ошибок. Если в статье или инструкции нужен пример, используйте заведомо фиктивную строку и подпишите её как условную. Реальный секрет в документации — это уже утечка, даже если документ «внутренний».

Подпись подтверждает отправителя, но не его полномочия

Вот тонкость, которую пропускают чаще всего. Валидная подпись говорит: запрос собрал держатель секрета, и тело не менялось. Она ничего не говорит о том, имеет ли этот отправитель право менять именно эту запись в CRM. Если один и тот же секрет используется для нескольких типов событий или нескольких магазинов, то валидная подпись от «магазина А» технически позволяет прислать событие, которое приёмник применит к данным «магазина Б», если в теле указан чужой идентификатор.

Поэтому проверка источника — это два независимых шага. Первый: подпись верна. Второй: то, что пришло в теле, разрешено этому отправителю. Второй шаг — это уже авторизация, и её нельзя заменить криптографией. Практически это значит: в конфигурации приёмника у каждого отправителя свой секрет (или свой набор секретов), а в обработчике есть правило, какие сущности и поля этот отправитель вправе трогать. Подпись от одного источника не должна открывать запись в данные другого.

OWASP в шпаргалке по аутентификации разводит подтверждение личности и последующую авторизацию — ровно потому, что одно не вытекает из другого (OWASP: Authentication Cheat Sheet). В контексте вебхуков это переводится так: HMAC — это аутентификация отправителя, а маппинг «кто что может менять» — отдельный слой, который живёт в вашем коде, а не в заголовке.

Проверка подписи доставки: что приёмник должен знать о каждой доставке

Чтобы проверка не расползлась по коду случайными кусками, полезно зафиксировать форму записи о доставке — то, что приёмник сохраняет и по чему потом разбирается инцидент. Это не схема БД на все случаи, а минимальный набор полей, без которых проверку не отладить.

Хэш тела здесь — компромисс: он позволяет доказать, что байты не менялись между приёмом и разбором, не храня при этом персональные данные в открытом виде. Если позже понадобится сверить конкретную доставку, хэш сойдётся или нет — и это уже сигнал.

Форма объекта важна ещё и потому, что она задаёт границу ответственности. Всё, что попало в запись о доставке, — это факты о транспорте. Всё, что попало в CRM, — это факты о бизнес-событии. Смешивать их в одной таблице удобно ровно до первого инцидента, когда нужно ответить на вопрос «что именно мы приняли и на каком основании».

Эпизод второй: подпись верна, но доставка устарела

Условный сценарий. Платёжный провайдер шлёт событие «платёж подтверждён». Сеть моргнула, отправитель повторил доставку через час. Приёмник видит валидную подпись, свежее тело — и применяет событие. Проблема в том, что за этот час заказ уже отменили вручную, а повторная доставка вернула его в «оплачено». Подпись при этом честно подтверждает: да, это тот самый провайдер, да, тело не менялось. Но событие уже неактуально.

Отсюда правило: подпись — необходимое, но не достаточное условие. Рядом с ней нужна проверка свежести. Если контракт провайдера предусматривает подписанную временную метку, приёмник проверяет её по согласованному окну. Идентификатор события применяют для защиты от повторной обработки; сам по себе он не доказывает свежесть. Нельзя доверять произвольной неподписанной дате из заголовка. Размер окна — вопрос договорённости с отправителем и вашей переносимости к задержкам, а не универсальная константа. Важно, чтобы окно было явно задано и одинаково понималось обеими сторонами.

Второй слой — идемпотентность по идентификатору события. Если отправитель присылает уникальный идентификатор доставки, приёмник сохраняет его и при повторе видит: «это событие уже обработано» — и не применяет его второй раз. Это защита не от подделки, а от повторной доставки, и она работает независимо от того, верна подпись или нет. Подпись и идемпотентность решают разные задачи: первая — «откуда», вторая — «не дважды ли».

Третий слой — что делать, если проверка свежести провалилась, а подпись верна. Не молчать и не применять. Вернуть ошибку, зафиксировать в записи о доставке причину отказа и оставить событие на ручной разбор, если бизнес-логика допускает «поздние» события. Иногда позднее событие legitimately важно (например, отмена пришла с задержкой), и тогда правило «отбрасывать всё старое» слишком грубое. Это уже вопрос бизнес-правил, а не криптографии, и решать его должен владелец процесса, а не разработчик в одиночку.

Проверка подписи доставки на экране сотрудника

Проверка подписи — это код, но разбирается сбой человеком. Если сотрудник поддержки видит только «ошибка 401», он не сможет отличить «отправитель прислал не тот секрет» от «тело изменили по дороге» и от «доставка устарела». Поэтому у записи о доставке должен быть человекочитаемый вид — не сырой лог, а карточка с понятными полями.

В этой карточке полезно показать: когда пришла доставка, от какого отправителя, какой результат проверки подписи, совпал ли хэш тела с тем, что разбирали, прошла ли проверка свежести, и что в итоге применили к CRM. Секрет, разумеется, не показывается никогда — только метка, какой именно ключ использовался. Кнопка «повторить разбор» должна быть отделена от кнопки «применить вручную»: первая безопасна, вторая меняет данные и требует прав.

Отдельный вопрос — кто имеет право смотреть эту карточку. Тело события может содержать персональные данные, поэтому доступ к полному телу — не то же самое, что доступ к метаданным доставки. Разумно разделить роли: поддержка видит метаданные и результат проверки, а полное тело доступно только тем, кому оно нужно по работе, и с фиксацией факта просмотра. Это не бюрократия, а следствие того, что вебхук — это канал с персональными данными.

Наконец, интерфейс должен подсказывать следующий шаг. «Подпись не совпала» — значит, сверить секрет с отправителем и проверить, не менялся ли он. «Подпись отсутствует» — значит, проверить, тот ли адрес и тот ли отправитель. «Устарело» — значит, посмотреть, не было ли ручных изменений в CRM между событием и доставкой. Такие подсказки экономят часы разбора и снижают шанс, что сотрудник «на всякий случай» применит событие вручную.

Проверка подписи доставки: когда стандартная проверка не срабатывает

Первое исключение — прокси и балансировщики, которые пересобирают тело. Некоторые промежуточные узлы могут менять тело запроса: добавлять пробелы, менять кодировку, нормализовать заголовки. Если это происходит, подпись перестаёт сходиться на стороне приёмника, хотя отправитель всё сделал правильно. Лечение здесь одно: убедиться, что тело доходит до кода проверки в исходном виде, и проверить это на тестовой доставке, а не в проде. Если промежуточный узел неизбежно меняет тело, это нужно знать заранее и договариваться с отправителем о схеме, которая это переживёт, — а не ослаблять проверку.

Второе исключение — несколько отправителей на одном адресе. Если один приёмник обслуживает несколько источников, у каждого должен быть свой секрет и своя метка. Иначе подпись одного источника открывает запись в данные другого. Это возвращает нас к разделению аутентификации и авторизации: даже при верной подписи обработчик обязан проверить, что этот отправитель вправе менять именно эту сущность.

Третье исключение — смена алгоритма или формата заголовка на стороне отправителя. Провайдер может перейти с одного алгоритма подписи на другой или изменить имя заголовка. Приёмник, который жёстко зашит на один формат, начнёт отвергать всё. Поэтому в записи о доставке полезно хранить, каким алгоритмом и каким заголовком подписали, — тогда переход виден в данных, а не только в переписке с поддержкой провайдера.

Четвёртое исключение — доставки, которые приходят до того, как вы успели настроить секрет, или после того, как отключили старый. Это нормальный шум переходного периода. Он не должен ни применяться, ни теряться бесследно: пусть попадает в запись о доставке с понятной причиной, чтобы потом можно было решить, нужно ли его воспроизвести вручную.

Пятое — тестовые доставки от отправителя. Их полезно помечать отдельно, чтобы они не смешивались с боевыми в статистике и не применялись к реальным данным. Это мелочь, которая экономит нервы при разборе «а почему у нас лид с суммой 1 рубль».

Как проверить, что проверка действительно работает

Проверку подписи легко «сделать» так, что она всегда возвращает «ок». Поэтому её нужно проверять намеренно, а не надеяться на боевой трафик. Ниже — набор тестов, которые стоит прогнать до того, как приёмник начнёт менять данные в CRM. Все сценарии — условные, на фиктивных секретах.

Отдельно стоит проверить, что при отказе приёмник не оставляет «полуприменённых» изменений. Если обработчик успел создать сделку, а потом упал на проверке свежести, — это баг, а не особенность. Проверки должны идти до записи, а запись — быть атомарной настолько, насколько это позволяет ваша CRM.

И ещё один тест, который часто забывают: проверка на утечку секрета в логи. Прогоните сценарий с неверной подписью и посмотрите, не попал ли секрет или полное тело в лог ошибки. Если попал — это уже инцидент, даже если функционально всё работает.

Практикум: разбираем условную доставку по шагам

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

Шаг первый — смотрим запись о доставке, а не сырой лог. Что там: результат проверки подписи, хэш тела, метка времени, идентификатор отправителя. Допустим, подпись «ok», хэш совпал, но проверка свежести не прошла: метка события на два дня старше окна. Значит, проблема не в подписи, а в том, что доставка пришла с опозданием. Это уже другой разбор.

Шаг второй — выясняем, почему опоздала. Смотрим, не было ли повторов, не менялся ли адрес приёмника, не отключался ли сервис. Если доставка пришла после сбоя на стороне отправителя, это нормальный сценарий, и вопрос в том, нужно ли применять поздние события. Здесь решение принимает владелец процесса: для статуса «вручено» позднее событие, скорее всего, полезно, а для «оплачено» — может быть опасно.

Шаг третий — если решено применить вручную, делаем это через интерфейс с фиксацией, кто и когда применил, а не правкой в базе. Так у нас остаётся след: событие было, подпись верна, применено вручную по такой-то причине. Это важно для последующего разбора и для того, чтобы не потерять связь между доставкой и изменением в CRM.

Шаг четвёртый — если выяснилось, что подпись «ok» на самом деле потому, что приёмник проверяет подпись от пересобранного тела и она случайно совпала, — это худший исход. Он означает, что проверка не работает, а вы об этом не знали. Поэтому в практикуме всегда есть шаг «сломай намеренно»: измените тело в тестовой доставке и убедитесь, что приёмник отказывает. Если не отказывает — чините проверку до того, как разбирать что-то ещё.

Что сверить с уполномоченным сотрудником, а не решать в коде

Часть вопросов вокруг вебхуков выходит за рамки инженерии. Сколько хранить записи о доставках, можно ли хранить тело события с персональными данными и как долго, кто имеет право просматривать эти данные, нужно ли уведомлять субъектов — всё это регулируется применимыми документами и внутренними политиками, а не нашим удобством. Эти вопросы стоит вынести на уполномоченного сотрудника — того, кто отвечает за защиту данных и соответствие требованиям, — и зафиксировать ответы до того, как приёмник начнёт копить тела событий «на всякий случай».

То же касается условий безопасности инфраструктуры: где хранятся секреты, как ограничивается сетевой доступ к приёмнику, какие требования предъявляются к журналированию. Мы можем описать методику проверки подписи, но не можем устанавливать за вас обязанности и сроки по закону или условия защищённости оборудования. Это зона ответственного сотрудника и применимых документов.

Практический вывод для команды: перед запуском приёмника составьте короткий список вопросов к уполномоченному сотруднику — срок хранения метаданных и тел, круг доступа, порядок реакции на инцидент с утечкой секрета. Ответы на них — такая же часть готовности интеграции, как и работающий HMAC.

Начните с проверки исходных байтов доставки

Если из всей статьи нужен один конкретный шаг, вот он. Возьмите текущую тестовую доставку от вашего отправителя, сохраните её тело как байты, посчитайте HMAC тем же секретом и сравните с заголовком — вручную, вне кода приёмника. Если подпись сходится на исходных байтах, но не сходится на пересобранном JSON, — вы нашли ту самую ошибку, из-за которой проверка может быть фиктивной. Если же подпись сходится и после пересборки, это не делает такую проверку правильной: зафиксируйте в коде правило «считать от сырых байтов», чтобы случайное совпадение не стало нормой.

Дальше — по одному пункту из таблицы тестов: изменённое тело, неверный секрет, отсутствие заголовка, устаревшая метка, повтор с тем же идентификатором. Каждый прогон должен давать отказ с понятной причиной в записи о доставке и не оставлять изменений в CRM. Это скучная работа, но именно она отделяет настоящую проверку источника от декоративной.

И последнее. Подпись вебхука — это не функция, которую «включили», а контракт между отправителем и приёмником: что подписывается, каким алгоритмом, каким заголовком, какое окно свежести, какие секреты активны. Пока этот контракт не зафиксирован письменно и не покрыт тестами, зелёные логи ничего не доказывают. Когда он зафиксирован — у вас есть основание доверять входящей доставке ровно настолько, насколько вы её проверили, и ни на грамм больше.

Смежный вопрос разобран отдельно: Повторные вебхуки CRM: одно событие не должно создавать две задачи.