Тестування вебхуків 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

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

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

GitHub підписує кожен payload вашим 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 із вбудованою видимістю запитів.