Как защитить webhook SMS API от подмены и повторных запросов

Как защитить webhook SMS API от подмены и повторных запросов

Начните с проверки: подтверждает ли ваше приложение подпись webhook до того, как меняет статус SMS? Для защиты входящих уведомлений нужны HTTPS, проверка подлинности запроса и защита от его повторного выполнения. Webhook — это запрос, которым SMS-провайдер сообщает вашему приложению результат доставки. Ниже разберём, что поручить разработчику, как проверить настройку и почему даже корректный статус нельзя обрабатывать без связи с исходным сообщением. Такой порядок подходит и небольшому интернет-магазину, и сервису с постоянным потоком уведомлений.

Почему HTTPS недостаточно для защиты статуса SMS?

HTTPS защищает соединение между отправителем запроса и вашим сервером. Однако общедоступный адрес webhook сам по себе не подтверждает, что запрос пришёл от SMS-провайдера. Если приложение принимает любой запрос с подходящими полями, посторонний отправитель сможет попытаться изменить статус сообщения.

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

Подпись позволяет проверить подлинность запроса и целостность тех данных, которые она охватывает. Но точный способ проверки задаёт провайдер: какие поля участвуют, в каком порядке и как передаётся результат. Попросите разработчика найти эту схему в документации вашего SMS API. Собственная догадка о формате подписи здесь не подходит.

Отдельно различайте приём сообщения шлюзом и доставку на телефон. Статус accepted означает, что система приняла запрос на отправку; результат приходит позднее через DLR или webhook (источник: smpp.by, «Как построить очередь SMS в API и SMPP: rate limit и приоритеты»). Разобраться в этих различиях поможет материал про статусы доставки SMS и детали отчётности.

Как проверять подпись webhook до изменения статуса?

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

  1. Принять запрос через HTTPS и ограничить допустимый метод, тип содержимого и размер тела согласно формату интеграции.
  2. Сохранить исходное тело запроса для проверки в рамках его обработки, прежде чем разбирать и преобразовывать содержимое.
  3. Проверить обязательные поля подписи и вычислить ожидаемое значение точно по схеме провайдера.
  4. Сравнить подписи специальной функцией криптографической библиотеки, которая не раскрывает совпавшую часть через время сравнения.
  5. Только после успешной проверки передать событие на проверку времени, повторов и допустимости смены статуса.

Частая техническая ловушка — повторная сборка JSON перед вычислением подписи. Если провайдер подписывает исходные байты тела, изменение пробелов или порядка полей нарушит проверку. Разработчику нужно использовать именно тот набор данных, который описан в документации, без предварительного «приведения к красивому виду».

Секрет для проверки подписи держат в защищённых настройках сервера. Его не включают в адрес webhook, клиентский код или диагностические сообщения. Если провайдер использует асимметричную подпись, проверку выполняют его открытым ключом; общий секрет в такой схеме не нужен.

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

Как отличить повторную доставку webhook от атаки?

Корректную подпись можно прислать повторно вместе с исходным запросом. Поэтому одна подпись не защищает от повторного воспроизведения. Для этого проверяют время запроса и учитывают события, которые приложение уже обработало.

Если схема провайдера предусматривает метку времени, убедитесь, что подпись охватывает и её. Иначе отправитель поддельного запроса сможет заменить время отдельно от остального содержимого. Допустимое отклонение согласуйте с правилами повторной доставки провайдера и настройками часов сервера. Универсальный интервал здесь только создаст лишние отказы.

Уточните, какое время приходит в webhook: момент события у оператора или момент отправки запроса. Это разные значения. Поздний статус доставки нельзя автоматически считать подделкой только из-за давнего времени самого события.

Повторный webhook встречается и при штатной работе: приложение обработало событие, но провайдер не получил подтверждение и отправил его снова. При идемпотентной обработке такой повтор не меняет результат и не запускает связанные действия заново. Аналогичный принцип помогает сопоставлять message_id и не терять статусы SMS: событие должно относиться к конкретной отправке, а не просто к номеру получателя.

  • Используйте уникальный идентификатор события провайдера, если он предусмотрен. Один message_id часто объединяет несколько разных изменений статуса.
  • Если идентификатора события нет, согласуйте состав ключа повтора по доступным полям. Не отбрасывайте все последующие уведомления для одного сообщения.
  • Фиксируйте приём события и изменение статуса атомарно, то есть как неделимую операцию, чтобы параллельные запросы не выполнили действие дважды.
  • Для уже обработанного корректного события возвращайте подтверждение по правилам API, не повторяя бизнес-действия.

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

Что проверить после подписи и защиты от повторов?

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

Затем проверьте допустимость перехода между статусами. Уведомления могут прийти с задержкой или в другом порядке, поэтому правило «последний запрос всегда побеждает» искажает результат. Таблицу переходов разработчик составляет по перечню статусов конкретного провайдера. Если API поддерживает уточнение статуса, спорное событие можно сверить через этот механизм.

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

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

Типичные ошибки при защите webhook

  • Считать скрытый адрес достаточной защитой. Исправление: проверять подлинность каждого запроса способом, который поддерживает провайдер.
  • Доверять списку IP-адресов как единственной проверке. Исправление: использовать его как дополнительный фильтр, если провайдер публикует и поддерживает такой список.
  • Менять статус до проверки подписи. Исправление: вынести проверку перед любыми изменениями и запуском связанных действий.
  • Отклонять все повторные запросы как поддельные. Исправление: отдельно проверять подлинность и отдельно обеспечивать идемпотентность обработки.
  • Проверять только успешный сценарий. Исправление: испытать изменённое тело, отсутствие подписи, повтор события и запрос с недопустимым временем.

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

Следующий шаг на две минуты: отправьте разработчику вопрос «Проверяем ли мы подпись webhook до изменения статуса SMS и что происходит при повторе того же события?».