Tham gia danh sách chờ
Tất cả bài viết
Các sự kiện repository chảy dưới dạng webhook vào một laptop phát triển cục bộ.
GitHubwebhook debugginglocal testingCI/CD

Kiểm thử webhook GitHub cục bộ: hướng dẫn đầy đủ

Kiểm thử webhook GitHub cục bộ cho phép bạn nhận sự kiện push, pull request, issue và workflow trên máy mình mà không cần deploy lên staging. Chạy một tunnel localhost, đăng ký URL HTTPS trong cài đặt GitHub App hoặc repository của bạn, rồi gỡ lỗi handler với xác minh chữ ký đầy đủ.

Vì sao webhook GitHub cần một endpoint công khai

GitHub gửi sự kiện webhook dưới dạng yêu cầu HTTP POST tới một URL đã cấu hình. Máy cục bộ của bạn tại 127.0.0.1 không thể tiếp cận từ máy chủ của GitHub. Một tunnel localhost cung cấp endpoint HTTPS công khai mà GitHub yêu cầu.

GitHub Apps vs webhook repository

Webhook repository

Cấu hình theo từng repository tại Settings → Webhooks. Tốt để kiểm thử handler sự kiện của một repo trong lúc phát triển tính năng.

Webhook GitHub App

Cấu hình ở cấp app trong cài đặt GitHub App của bạn. Cần thiết khi xây tích hợp phục vụ nhiều repository hoặc organization.

Cả hai kiểu gửi đều dùng xác minh chữ ký HMAC-SHA256 qua header X-Hub-Signature-256.

Từng bước: kiểm thử webhook GitHub cục bộ

  1. Khởi động app cục bộ với một endpoint webhook (ví dụ /api/webhooks/github).
  2. Chạy npx portpreview 3000 để có URL HTTPS công khai.
  3. Trong GitHub, thêm URL tunnel cộng đường dẫn webhook làm payload URL.
  4. Đặt content type là application/json và chọn sự kiện cần nhận.
  5. Tạo một webhook secret và lưu vào biến môi trường cục bộ.
  6. Kích hoạt sự kiện (push một commit, mở PR, tạo issue) và kiểm tra các lần gửi.
  7. Xác minh handler kiểm tra chữ ký và trả về phản hồi 2xx trong vòng 10 giây.

Xác minh chữ ký webhook GitHub cục bộ

GitHub ký mỗi payload bằng webhook secret của bạn. Handler của bạn phải:

  • Đọc body thô của yêu cầu trước khi phân tích JSON.
  • Tính HMAC-SHA256 bằng secret của bạn.
  • So sánh với header X-Hub-Signature-256 bằng so sánh thời gian hằng số.

Các công cụ tunnel giữ nguyên header gốc cho phép bạn kiểm thử đường xác minh thật. Đừng bao giờ bỏ qua kiểm tra chữ ký khi phát triển cục bộ.

Các sự kiện nên kiểm thử cục bộ

  • push — logic kích hoạt CI, hook bảo vệ nhánh, pipeline triển khai.
  • pull_request — tự động hóa review, bot nhãn, kiểm tra merge.
  • issues — đồng bộ tracker issue, luồng phân công.
  • installation — vòng đời cài/gỡ GitHub App.
  • workflow_run — tự động hóa sau CI và xử lý artifact.

Gỡ lỗi các lần gửi webhook GitHub thất bại

GitHub thử lại các lần gửi thất bại với backoff lũy thừa. Lỗi thường gặp khi kiểm thử cục bộ:

  • Handler timeout (GitHub mong phản hồi trong 10 giây).
  • Chữ ký không khớp do phân tích body trước khi xác minh.
  • Phiên tunnel hết hạn trong lúc GitHub thử lại.
  • Bộ lọc sự kiện sai — handler nhận sự kiện nó không xử lý.

Dùng phát lại webhook để kiểm thử lại các lần gửi thất bại mà không cần push commit mới.

Kiểm thử webhook GitHub vs smee.io

smee.io là một proxy webhook GitHub phổ biến cho phát triển cục bộ. Nó hoạt động tốt cho việc chuyển tiếp cơ bản nhưng thiếu kiểm tra yêu cầu và phát lại tích hợp sẵn. PortPreview kết hợp tunnel với bắt và phát lại trong một công cụ. Để có hướng dẫn gỡ lỗi webhook rộng hơn, xem cách gỡ lỗi webhook cục bộ.

Tham gia danh sách chờ của PortPreview để kiểm thử webhook GitHub với khả năng thấy yêu cầu tích hợp sẵn.

Câu hỏi thường gặp

Làm sao tôi kiểm thử webhook GitHub trên localhost?
Khởi động một tunnel localhost với PortPreview, thêm URL HTTPS làm payload URL webhook trong cài đặt repository hoặc App GitHub của bạn, rồi kích hoạt sự kiện và kiểm tra từng lần gửi.
Xác minh chữ ký GitHub có hoạt động với tunnel không?
Có. PortPreview giữ nguyên header X-Hub-Signature-256 và body thô của yêu cầu nên xác minh HMAC hoạt động y như trên production.
Điều gì xảy ra nếu handler cục bộ của tôi quá chậm với GitHub?
GitHub mong một phản hồi 2xx trong 10 giây, nếu không nó đánh dấu lần gửi là thất bại và thử lại. Dùng xử lý bất đồng bộ cho tác vụ chạy lâu và trả về 202 ngay lập tức.