How Do GitHub Webhooks Work?
git push → HTTP POST → CI/CD Trigger
GitHub Webhooks work by registering a URL in Repository Settings > Webhooks. When an event occurs, GitHub sends an HTTP POST with a JSON payload to that URL. The X-Hub-Signature-256 header includes an HMAC signature to verify the request authenticity. The receiving server must return 200 OK within 10 seconds, and GitHub automatically retries on failure.
Architecture Diagram
actual = request.headers["X-Hub-Signature-256"]
secure_compare(expected, actual) # true → valid
- Must return 200 OK within 10 seconds (heavy processing should be done in background)
- GitHub auto-retries on failure (up to 3 times)
- Delivery logs available in Settings → Webhooks
- ngrok needed for local development (no public URL)
How It Works
Register Webhook URL + Secret in Repository Settings
Developer runs git push (or creates PR, Issue, etc.)
GitHub sends HTTP POST to registered URL (JSON payload)
HMAC-SHA256 signature included via X-Hub-Signature-256 header
Receiving server verifies signature then processes event (CI/CD trigger, etc.)
Server returns 200 OK (within 10s, GitHub retries on failure)
Pros
- ✓ Very simple setup
- ✓ Fine-grained event type selection
- ✓ Automatic retry on failure
- ✓ Delivery logs viewable in GitHub UI
Cons
- ✗ Public URL required (ngrok needed for local development)
- ✗ 10-second timeout (heavy processing must be async)
- ✗ Signature verification implementation needed
- ✗ No event ordering guarantee