Как тестировать вебхуки GitHub на localhost?

Запустите localhost-туннель с PortPreview, добавьте HTTPS-URL как payload URL вебхука в настройках вашего репозитория или App GitHub, затем запускайте события и осматривайте каждую доставку.

Работает ли проверка подписи GitHub с туннелем?

Да. PortPreview сохраняет заголовок X-Hub-Signature-256 и сырое тело запроса, так что проверка HMAC работает так же, как в продакшене.

Что произойдёт, если мой локальный обработчик слишком медленный для GitHub?

GitHub ждёт ответ 2xx в течение 10 секунд, иначе помечает доставку как неудавшуюся и повторяет. Используйте асинхронную обработку для долгих задач и сразу возвращайте 202.

Тестирование вебхуков GitHub локально: полное руководство

Локальное тестирование вебхуков GitHub позволяет получать события push, pull request, issue и workflow прямо на вашей машине без деплоя в staging. Запустите localhost-туннель, зарегистрируйте HTTPS-URL в настройках вашей GitHub App или репозитория и отлаживайте обработчики с полной проверкой подписи.

Почему вебхукам GitHub нужен публичный endpoint

GitHub доставляет события вебхуков как HTTP-POST-запросы на настроенный URL. Ваша локальная машина на 127.0.0.1 недоступна серверам GitHub. localhost-туннель предоставляет публичный HTTPS-endpoint, которого требует GitHub.

GitHub Apps против вебхуков репозитория

Вебхуки репозитория

Настраиваются по репозиторию в Settings → Webhooks. Хороши для тестирования обработчиков событий одного репозитория при разработке фичи.

Вебхуки GitHub App

Настраиваются на уровне приложения в настройках вашей GitHub App. Нужны при создании интеграций, обслуживающих несколько репозиториев или организаций.

Оба типа доставки используют проверку подписи HMAC-SHA256 через заголовок X-Hub-Signature-256.

Пошагово: локальное тестирование вебхуков GitHub

Запустите локальное приложение с endpoint для вебхука (например, /api/webhooks/github).
Выполните npx portpreview 3000, чтобы получить публичный HTTPS-URL.
В GitHub добавьте URL туннеля плюс ваш путь вебхука как payload URL.
Установите content type в application/json и выберите события для получения.
Сгенерируйте webhook secret и храните его в локальных переменных окружения.
Запускайте события (запушьте коммит, откройте PR, создайте issue) и осматривайте доставки.
Убедитесь, что обработчик проверяет подпись и возвращает ответ 2xx в течение 10 секунд.

Проверка подписей вебхуков GitHub локально

GitHub подписывает каждую полезную нагрузку вашим webhook secret. Ваш обработчик должен:

Прочитать сырое тело запроса до разбора JSON.
Вычислить HMAC-SHA256 с вашим секретом.
Сравнить с заголовком X-Hub-Signature-256, используя сравнение за постоянное время.

Инструменты-туннели, сохраняющие исходные заголовки, дают протестировать реальный путь проверки. Никогда не пропускайте проверку подписи при локальной разработке.

События для локального тестирования

push — логика триггера CI, хуки защиты веток, пайплайны деплоя.
pull_request — автоматизация ревью, боты меток, проверки слияния.
issues — синхронизация трекера задач, рабочие процессы назначения.
installation — жизненный цикл установки/удаления GitHub App.
workflow_run — пост-CI-автоматизация и обработка артефактов.

Отладка неудавшихся доставок вебхуков GitHub

GitHub повторяет неудавшиеся доставки с экспоненциальной задержкой. Частые сбои при локальном тестировании:

Таймаут обработчика (GitHub ждёт ответ в течение 10 секунд).
Несовпадение подписи из-за разбора тела до проверки.
Сессия туннеля истекла, пока GitHub повторяет.
Неверный фильтр событий — обработчик получает события, которые не обрабатывает.

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

Тестирование вебхуков GitHub против smee.io

smee.io — популярный прокси вебхуков GitHub для локальной разработки. Он хорошо подходит для простой пересылки, но ему не хватает встроенного осмотра запросов и повтора. PortPreview объединяет туннелирование с захватом и повтором в одном инструменте. Более широкое руководство по отладке вебхуков см. в как отлаживать вебхуки локально.

Запишитесь в лист ожидания PortPreview ради тестирования вебхуков GitHub со встроенной видимостью запросов.