🔐 HMAC in Action: How webhook-listener.js Keeps Your Civic API Spoof-Free 🛡️

🔐 HMAC Verification in webhook-listener.js

Secure your civic API with signature checks, no spoofing, and verified GitHub events…

🧠 What Is HMAC Verification?

HMAC stands for Hash-based Message Authentication Code. It’s a cryptographic technique used to verify that a message (like a webhook from GitHub) is:

• ✅ Authentic — sent by the real source
• ✅ Untampered — not changed during transit

Think of it as a secret handshake between GitHub and your server. If the handshake doesn’t match, the message gets rejected.

📦 Why Is It in api/webhook-listener.js?

This file is a serverless API endpoint that listens for incoming webhooks from GitHub. Webhooks are automated messages GitHub sends when something happens—like a push, star, or issue.

But anyone could try to fake a webhook. That’s where HMAC comes in.

🛠️ How It Works

1. GitHub sends a webhook with a special header called x-hub-signature-256.
2. Your server uses the same secret key to generate its own hash of the message.
3. It compares the two hashes:
   • If they match → ✅ Message is real
   • If they don’t → ❌ Message is rejected

🔍 Code Snippet

const signature = req.headers['x-hub-signature-256']; const payload = JSON.stringify(req.body); const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET); hmac.update(payload); const expectedSignature = `sha256=${hmac.digest('hex')}`; if (signature !== expectedSignature) { return res.status(401).json({ error: 'Invalid signature' }); }

🧩 Why It Matters

• 🛡️ Security: Prevents fake or malicious data from entering your civic dashboard
• 📊 Integrity: Ensures only verified GitHub events trigger updates
• 🔍 Auditability: Logs every verified event with timestamp and metadata
• 🚫 No Spoofing: Blocks bots or attackers from injecting false data

📚 Glossary (Kid-Friendly)

Term	Meaning
HMAC	A secret math check to prove a message is real
Webhook	A message GitHub sends when something happens
Signature	A special code that proves the message is safe
Secret Key	A password used to generate and verify the signature
Hash	A scrambled version of the message used for verification
Serverless	Code that runs online without managing a physical server

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

MIT License © 2025 Peter M. Mutiti · View License