"Webhooks: The Internet's Little Messengers You Didn't Know You Needed 🚪📡⚡"

GitHub Webhooks API Guide for Civic Builders

🛠️ Automate Responses • 🔐 Secure Payloads • 🌍 Build for Public Transparency

“Repository webhooks allow your civic tool or server to respond in real time to GitHub events — enabling automation, transparency, and engagement.”

📣 Update: GitHub's REST API is now versioned. Add header X-GitHub-Api-Version: 2022-11-28 to all requests.

🔍 What Are Webhooks?

Webhooks send HTTP POST payloads to your server whenever events like push or pull_request occur. They help automate civic dashboards, trigger builds, or notify services.

📦 Listing Webhooks

• Endpoint: GET /repos/{owner}/{repo}/hooks
• Permissions: Webhooks: read access token required
• Headers: Accept, Authorization, and X-GitHub-Api-Version

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer YOUR-TOKEN" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/hooks

✏️ Creating Webhooks

{ "name": "web", "config": { "url": "https://your-app.com/webhook", "content_type": "json", "insecure_ssl": "0" }, "events": ["push"], "active": true }

Each webhook must have a unique URL or distinct set of events to avoid collisions.

🔐 Verifying Payload Signatures

GitHub sends a signature header X-Hub-Signature-256. Use HMAC to verify:

// Node.js const crypto = require('crypto'); const verify = (body, signature, secret) => { const hash = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex'); return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash)); };

🌐 Deployment Options

• Local Dev: Node.js + Ngrok
• Serverless: Vercel Edge Functions, Supabase
• Cloud Logging: Store webhook results in Supabase for public observability

🧪 Testing Webhooks

• Use GitHub’s “Ping” tool under repo → Settings → Webhooks
• Mock requests with CLI tools or Postman
• Tunnel local dev with Ngrok

🚀 Remix Ideas

• Display webhook event history in your civic dashboard
• Use Supabase or Vercel KV to cache recent push events
• Build region-aware monitors for repo activity

Author: Peter M. Mutiti | Investigative Journalist & Civic Technologist

MIT License © 2025 Peter M. Mutiti · View License