🔁 🔐 HMAC, Hashtags & Audit Gaps: Fixing Your Serverless Webhook for Real-Time Trust 🛠️

📦 GitHub Webhooks Decoded

Why your serverless listener isn’t rotating civic hashtags or verifying GitHub events…

🛠️ What’s Missing
❌ No logic to extract or rotate hashtags
❌ No storage or update mechanism
❌ No raw body capture for HMAC integrity (needed on platforms like Vercel)

🔍 Hashtag Rotation Logic

Your listener doesn’t parse commit messages, issue titles, or PR descriptions for hashtags. There’s no function to:

• Extract #tags from payloads
• Store them in a rotating queue or database
• Update civic dashboards or rolling tickers

✅ Fix: Add a parser that scans req.body for hashtags and pushes them to a rotation module or Redis queue.

📦 Storage and Update Mechanism

Even if hashtags are extracted, they’re not saved anywhere. No database, cache, or file system is used to persist or rotate them across sessions.

✅ Fix: Use a lightweight store (e.g., Redis, Supabase, or Firebase) to log hashtags and rotate them every X minutes.

🔐 Raw Body Capture for HMAC Integrity

Platforms like Vercel parse the body before you can hash it, breaking HMAC verification. GitHub signs the raw payload, so you must capture it before any parsing.

// Example for Vercel export const config = { api: { bodyParser: false, }, }; import { buffer } from 'micro'; const rawBody = await buffer(req);

✅ Fix: Use req.rawBody or a custom body parser middleware to preserve the raw string for HMAC comparison.

🧭 Civic Impact

• 🚫 Your dashboard won’t reflect trending civic hashtags
• 🛑 You risk spoofed or tampered GitHub events
• 📉 Your API loses audit-grade integrity

✅ With these fixes, you get verified, rotating civic signals and build public confidence in your infrastructure.

📚 Glossary (Kid-Friendly)

Term	Meaning
Webhook	A message GitHub sends when something happens
Hashtag	A keyword with # used to tag topics
Rotation	Changing what’s shown every few seconds or minutes
HMAC	A secret math check to prove a message is real
Raw Body	The untouched message before any changes
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

🔐 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

📦 Vercel, Netlify, Lambda: Which Runtime Powers Your Serverless API Best? 🔍

🧠 Do You Need Node.js for a Serverless API?

Node.js isn’t mandatory—but it’s fast, popular, and civic-dashboard friendly…

No, you don’t need Node.js specifically—but it’s one of the most popular and supported options.

✅ What You Do Need

You need a runtime that can execute your API logic in the cloud. Serverless platforms like Vercel, Netlify, AWS Lambda, or Cloudflare Workers support multiple runtimes:

Runtime	Language	Example Use Case
Node.js	JavaScript / TypeScript	Most common for web APIs, npm support
Python	Flask, FastAPI	Data science, ML, scripting
Go	Fast, compiled APIs	Low-latency, high-performance APIs
Deno	TypeScript-native	Secure, modern alternative to Node
Rust, Java, etc.	Advanced use cases	Less common in serverless setups

🧩 Why Node.js Is Popular for Serverless

• ✅ Works out of the box on Vercel, Netlify, AWS Lambda
• ✅ Massive ecosystem (npm)
• ✅ Easy to write, deploy, and debug
• ✅ Same language as frontend (JavaScript)

🛠️ Example: Vercel Serverless API with Node.js

// api/hello.js export default function handler(req, res) { res.status(200).json({ message: "Hello from Node.js Serverless!" }); }

🧭 Bottom Line

You don’t need Node.js—but it’s often the fastest way to get started, especially if you’re already using JavaScript for your frontend or civic dashboards.

📚 Glossary of Terms (Kid-Friendly)

Term	Meaning
Serverless	Running code online without managing a server
Runtime	The environment where your code runs
Node.js	A tool that runs JavaScript on the server
API	A way for apps to talk to each other
npm	A library of tools for JavaScript developers
Frontend	The part of a website you see and use
Cloud	Computers on the internet that run your code

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

MIT License © 2025 Peter M. Mutiti · View License

📦 GitHub Webhooks Decoded: Why Your Serverless Listener Isn’t Rotating Hashtags 🔁

🔍 Dissecting webhook-listener.js

Understanding serverless verification logic and civic-grade webhook security for GitHub events…

📦 The Code

import crypto from 'crypto'; const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; export default async function handler(req, res) { if (req.method !== 'POST') { return res.status(405).json({ error: 'Method Not Allowed' }); } try { const signature = req.headers['x-hub-signature-256'] || req.headers['X-Hub-Signature-256']; const payload = JSON.stringify(req.body); if (!signature || !WEBHOOK_SECRET) { throw new Error('Missing signature or secret'); } 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' }); } const event = req.headers['x-github-event'] || 'unknown'; const delivery = req.headers['x-github-delivery'] || 'unknown'; const timestamp = new Date().toISOString(); console.log(`[${timestamp}] ✅ Webhook received: ${event} | Delivery: ${delivery}`); res.status(200).json({ status: '✅ Verified webhook received', event, delivery, timestamp, }); } catch (err) { console.error(`❌ Webhook error: ${err.message}`); res.status(500).json({ status: '❌ Webhook failed', error: err.message, }); } }

🧠 What This Code Does

• Imports crypto: Uses Node.js crypto module to verify message authenticity
• Checks request method: Only allows POST requests (as GitHub sends webhooks via POST)
• Extracts signature: Reads the HMAC signature from GitHub headers
• Recalculates signature: Uses your secret to recreate the expected signature
• Compares signatures: If they don’t match, the request is rejected
• Logs metadata: Captures event type, delivery ID, and timestamp
• Sends response: Returns success or failure message

🔍 Why It Matters

This function protects your civic API from fake or malicious requests. It ensures only GitHub can trigger your logic.

Without this verification, anyone could send spoofed data to your endpoint—breaking trust and polluting your dashboard.

🛠️ What’s Missing

• ❌ No logic to extract or rotate hashtags
• ❌ No storage or update mechanism
• ❌ No raw body capture for HMAC integrity (needed on platforms like Vercel)

📚 Glossary of Terms (Kid-Friendly)

Term	Meaning
Webhook	A message GitHub sends to your app when something happens
Serverless	A way to run code online without managing a server
HMAC	A secret math check to make sure the message is real
Payload	The actual message or data sent
Signature	A special code that proves the message is safe
Raw Body	The untouched message before it’s changed
Rotate	To change or update something regularly

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

MIT License © 2025 Peter M. Mutiti · View License

🛡️ Your Webhook’s Secret Weapon: How to Create Secure Keys with OpenSSL ⚙️

🔐 How to Generate a Secure Secret

Protect your webhook with a secret handshake using OpenSSL or any crypto tool…

A secure secret is like a secret password that only your app and GitHub know. It helps your webhook listener check if incoming messages are real and safe.

Think of it like a secret handshake—if it doesn’t match, the message gets rejected!

🧭 Step-by-Step Guide

✅ Step 1: Open Your Terminal

• On Mac or Linux: Open the Terminal app
• On Windows: Open Command Prompt or PowerShell

✅ Step 2: Type This Command

openssl rand -hex 32

✅ Step 3: Copy the Output

You’ll see something like:

9f3a7c2e1b6d4a8f3c1e2a7d9b5f6c3e9a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d

✅ Step 4: Paste It into Your .env File

WEBHOOK_SECRET=9f3a7c2e1b6d4a8f3c1e2a7d9b5f6c3e9a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d

✅ Step 5: Paste the Same Secret into GitHub Webhook Settings

• Go to your GitHub repo → Settings → Webhooks
• Add or edit your webhook
• Paste the same secret into the “Secret” field

✅ Without a secure secret, anyone could pretend to be GitHub and send fake messages to your app.

📚 Glossary of Terms (Kid-Friendly)

Term	Meaning
Secret	A private code only your app and GitHub know
OpenSSL	A tool that creates strong, random codes
Terminal	A place where you type commands to control your computer
Hexadecimal	A format for writing long codes using numbers and letters
.env file	A file where you store secrets and settings for your app
Webhook	A message GitHub sends to your app when something happens

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

MIT License © 2025 Peter M. Mutiti · View License

📦 From Delivery to Rotation: Making Serverless Webhooks Work for Trending Hashtags 🚀

🔁 Why Your Webhook Isn’t Rotating Hashtags

Troubleshooting webhook setup with friendly steps and civic-grade clarity…

Imagine your webhook is like a mailman delivering a message to your app. You expect it to bring new hashtags, but nothing ever changes. Why?

Your webhook is showing up, but it’s not bringing any hashtags because it doesn’t know what to do with them!

🧠 What the Code Does

• It checks if the message is real (using a secret key)
• It logs the type of message (like “push” or “star”)
• It sends back a “✅ Verified” message if everything looks good

❌ But it doesn’t actually grab or rotate any hashtags. That part is missing!

🛠️ How to Fix It

1. Capture the Raw Message
   Serverless apps sometimes change the message before you read it. You need to grab it raw:

   export const config = { api: { bodyParser: false, }, };

   Then use:

   import getRawBody from 'raw-body'; const rawBody = await getRawBody(req);

2. Add Hashtag Logic
   After verifying the message, extract hashtags and rotate them:

   const hashtags = extractHashtags(req.body); updateTrendingList(hashtags);

3. 
   - Go to your repo → Settings → Webhooks - Add your deployed URL (like `https://your-app.vercel.app/api/webhook-listener`) - Choose events like push or star - Use the same secret key as in your `.env` file

📚 Glossary of Terms

Term	Kid-Friendly Meaning
Webhook	A message sent from one website to another when something happens
Serverless	A way to run code online without managing a server
HMAC	A secret math check to make sure the message is real
Payload	The actual message or data sent
Signature	A special code that proves the message is safe
Raw Body	The untouched message before it’s changed
Rotate	To change or update something regularly

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

MIT License © 2025 Peter M. Mutiti · View License

📦 Why Your Webhook Arrived Empty: Fix It with Middleware Magic 🪄

🧠 What Is rawBody?

Explaining webhooks and middleware in kid-friendly language for civic learners…

Imagine your website is like a post office. Someone sends a package (a webhook), and your server needs to open it and check what’s inside.

But sometimes, the package arrives empty—your server can’t see what’s inside because it didn’t open it the right way.

So what do you do?

You use a helper (called middleware) to open the package before you try to read it.

🧪 Real-Life Analogy

If someone gives you a sealed envelope, you need to open it before reading the letter inside. Middleware is like the person who opens the envelope for you.

📚 Glossary of Terms

Term	Kid-Friendly Meaning
rawBody	The full message or data sent to your server, before it's changed
empty	Nothing inside—like an empty box
middleware	A helper tool that prepares things before your main code runs
capture	To grab or save something before it disappears
parsing	Breaking something into smaller parts so your code can understand it
webhook	A message sent from one website to another when something happens

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

MIT License © 2025 Peter M. Mutiti · View License

📦 From Payload to Proof: Verifying Webhooks with Crypto 🔍 + Node.js ⚙️

🔐 Webhook Listener: HMAC Verification Guide

Secure your civic endpoints with HMAC SHA256 verification and audit-grade secrets…

To ensure incoming webhook requests are authentic and untampered, the listener uses HMAC SHA256 verification with a shared secret (WEBHOOK_SECRET or GITHUB_WEBHOOK_SECRET).

HMAC verification is your first line of defense against spoofed or malicious webhook traffic.

🧭 Step-by-Step Setup

1. Generate a Secure Secret
   Use OpenSSL or any cryptographic tool:

   openssl rand -hex 32

   Example output:

   civic-rotator-override-9f3a7c2e1b6d4a8f3c1e2a7d9b5f6c3e

2. Set Environment Variables
   In .env or Vercel dashboard:

   WEBHOOK_SECRET=civic-rotator-override-9f3a7c2e1b6d4a8f3c1e2a7d9b5f6c3e GITHUB_WEBHOOK_SECRET=your-github-secret

3. Reference in Listener Code
   

   const secret = process.env.WEBHOOK_SECRET;

🧪 Example: HMAC Verification in api/webhook-listener.js

import crypto from 'crypto'; export default async function handler(req, res) { const signature = req.headers['x-signature'] || ''; const rawBody = JSON.stringify(req.body); const secret = process.env.WEBHOOK_SECRET; const hmac = crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); const isValid = crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature)); if (!isValid) { return res.status(401).json({ error: 'Invalid signature' }); } res.status(200).json({ status: 'Webhook verified', received: req.body }); }

⚠️ Common Issues & Fixes

Issue	Cause / Fix
Invalid signature	Signature header missing or incorrect secret used
crypto.timingSafeEqual fails	Buffer mismatch—ensure both values are hex strings of equal length
undefined process.env.SECRET	Environment variable not set or misnamed in Vercel
rawBody is empty	Use middleware to capture raw body before parsing

🧩 GitHub-Specific Notes:
Use the x-hub-signature-256 header and compute HMAC using:

crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

Strip the sha256= prefix before comparing.

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

MIT License © 2025 Peter M. Mutiti · View License

🔧 Why Node.js Is the Backbone 💪 of Modern Dashboards 📊, Stores 🛒, and Webhooks 🔁

What Is Node.js?

🧠 Node.js is the engine room of your civic app — fast, invisible, and powerful…

Node.js is like a brain for your website or app that runs behind the scenes. It’s not something users see. It’s the part that handles things like:

• Saving orders
• Sending emails
• Talking to databases
• Responding to webhooks
• Running timers, scrapers, or dashboards

Think of Node.js as the engine room of your online service.

🎯 What’s Its Purpose?

Node.js lets you write server-side logic using JavaScript—the same language used in browsers. That means:

• You don’t need to learn a separate backend language
• You can build both the frontend and backend using one language

⚡ It’s fast, lightweight, and perfect for real-time apps like chat, dashboards, or civic rotators.

🛠️ What Can You Use Node.js For?

Use Case	What Node.js Does
🛒 Online Store	Saves cart, processes orders, sends confirmation
📊 Civic Dashboard	Scrapes data, updates trends, serves API endpoints
📦 Webhook Listener	Verifies incoming requests, triggers actions
🗂️ File Uploader	Accepts files, stores them securely
🧠 AI Backend	Runs models, serves predictions
🔁 Cron Jobs	Runs tasks every hour, day, or week

🧪 Example

Let’s say someone clicks “Buy Now” on your site:

• The browser sends a request to your Node.js server
• Node.js checks the cart, saves the order, and sends a confirmation email
• You never see Node.js—but it’s doing all the heavy lifting

✅ Node.js is invisible to users, but essential for civic-grade infrastructure.