Структура запросов веб-перехватчиков
Веб-перехватчики (webhooks) представляют собой механизм обратного вызова, с помощью которого одна система уведомляет другую о возникновении события путем отправки HTTP-запроса. Понимание структуры этих запросов критически важно для API-разработчиков, инженеров по интеграции, специалистов службы поддержки и администраторов систем автоматизации.
Типичный запрос веб-перехватчика состоит из трех основных компонентов: метода HTTP, набора заголовков и тела запроса. Метод определяет тип операции (чаще всего используются POST, PUT, PATCH, GET или DELETE). Заголовки содержат метаданные о типе контента, авторизации и безопасности. Тело запроса несет в себе непосредственные данные о событии. Для успешной обработки веб-перехватчика принимающая сторона должна корректно разобрать все три компонента.
Роль заголовков в коммуникации веб-перехватчиков
Заголовки HTTP выполняют функцию инструкций по обработке запроса. Они сообщают серверу-получателю, как интерпретировать передаваемые байты и как удостовериться в подлинности отправителя.
Среди ключевых заголовков выделяются:
Content-Type: указывает формат данных в теле запроса (например,application/jsonилиapplication/x-www-form-urlencoded).- Заголовки подписей и меток времени: используются для обеспечения безопасности и предотвращения атак повторного воспроизведения. Отправители часто включают хэш-суммы (HMAC) и время генерации запроса в заголовки с именами, содержащими паттерны
signature,hmac,digestили временные метки.
Инструмент автоматически сканирует переданные заголовки на наличие этих паттернов и выводит их в разделе «Поля подписи». Если такие заголовки отсутствуют, отображается сообщение «Не найдена общая подпись или заголовок метки времени веб-перехватчика.».
Форматы тела веб-перехватчиков и особенности их обработки
Данные веб-перехватчиков обычно передаются в одном из двух распространенных форматов: JSON или URL-encoded (данные формы).
При анализе тела запроса действуют следующие правила:
- JSON: Тело парсится с помощью стандартного метода
JSON.parse. Это приводит к тому, что исходные пробелы, отступы и порядок полей теряются, так как объект перестраивается заново. Если структура нарушена, инструмент выдает ошибку «Тело выглядит как JSON, но не может быть проанализировано.». - URL-encoded: Данные формы декодируются и приводятся к читаемому структурированному виду. При наличии незавершенных последовательностей с символом процента возникает ошибка «Тело формы содержит неполный экранирующий процент.».
- Другие форматы: Любые другие типы данных не форматируются и отображаются в виде обычного текста. Если тело запроса отсутствует, выводится строка «(пустое тело)».
Для точной отладки крайне важно использовать именно необработанное тело запроса (raw body), полученное до какого-либо парсинга на стороне сервера. Любое изменение исходных байтов (например, нормализация пробелов сервером) сделает невозможной последующую проверку криптографических подписей.
Локальное тестирование с помощью cURL
После получения и анализа структуры веб-перехватчика возникает необходимость воспроизвести этот запрос в локальной среде разработки. Для этого используется утилита командной строки cURL.
Инструмент автоматически генерирует готовую команду cURL, которая жестко ориентирована на локальный адрес http://localhost:3000/webhooks. Эта команда содержит все переданные заголовки и экранированное тело запроса, что позволяет мгновенно отправить точную копию веб-перехватчика на локально запущенный сервис для отладки кода обработчика.
Проверка подлинности: инспектирование против верификации
Важно строго разграничивать процесс инспектирования структуры запроса и процесс верификации его подлинности.
Инструмент выполняет исключительно инспектирование: он находит и показывает заголовки подписей по характерным именам. Однако наличие поля подписи не доказывает подлинность запроса — для реальной проверки требуются правила подписи отправителя, секрет или ключ, а также исходные байты запроса. Инструмент не выполняет вычисление HMAC, не проверяет алгоритмы, не сопоставляет исходные байты, не использует секретные ключи, не проверяет окна повтора (replay window) и не производит специфичную для конкретных провайдеров верификацию.
Технические ограничения и обработка ошибок
При работе с инструментом необходимо соблюдать установленные лимиты на объем входных данных:
- Метод: Выбирается из фиксированного списка: POST, PUT, PATCH, GET, DELETE.
- Заголовки: Должны вводиться по одному на строку в формате
Имя: value. Максимальное количество непустых строк — 200, максимальная длина — 100 000 символов. При нарушении правил или превышении лимитов возникают ошибки:- «
‹line›: Строка заголовка недействительна. Имя использования: значение.» - «Слишком много строк заголовка. Держите запрос до 200 заголовков или меньше.»
- «Заголовки слишком длинные для этого инструмента. Удалите несвязанные или повторяющиеся значения.»
- «
- Тело: Максимальный размер ограничен 1 000 000 символов. При превышении лимита выводится ошибка «Корпус слишком длинный для этого инструмента. Не превышайте 1 000 000 символов.».
- Общее требование: Если попытаться запустить анализ пустого ввода, отобразится ошибка «Сначала вставьте хотя бы один заголовок или тело запроса.».
Конфиденциальность данных
Обработка всех вставленных данных происходит непосредственно в вашем браузере. Сервис BroBroGo не загружает введенные заголовки или тело запроса на сервер и не сохраняет их, обеспечивая выполнение обработки локально на стороне клиента.
Часто задаваемые вопросы
Может ли эта страница получить обратный вызов веб-перехватчика?
Нет. Вставьте сюда перехваченный запрос для проверки. Страница не создает общедоступную конечную точку, не принимает обратные вызовы и не отправляет сгенерированный тестовый запрос.
Какие форматы тела вебхука я могу проверить?
Тела форм в формате JSON и URL-кодируются и форматируются. Остальные тела остаются в виде обычного текста, поэтому инструмент не угадывает XML, составное или двоичное содержимое.
Подтверждает ли обнаружение поля подписи подлинность запроса?
Нет. Инструмент отображает только подписи и соответствующие заголовки меток времени. Для настоящей проверки необходимы точные правила подписи отправителя, секретный или открытый ключ и исходные байты запроса.