📬 Understanding GitHub Webhooks: Send Email Notifications on Pull Request Events Using Node.js

Recently, I became curious about how GitHub webhooks work. To deepen my understanding, I built a small Node.js project that sends an email notification every time a pull request (PR) is opened.

Yes, GitHub already has a built-in notification system, but building your own gives you full control and a deeper understanding of the ecosystem.

🔐 First, What’s HMAC?

Before we dive into code, it’s important to understand how GitHub ensures that webhook events are secure.

HMAC stands for Hash-based Message Authentication Code. It’s a cryptographic technique used to verify both:

• The integrity of a message (that it hasn’t been tampered with)
• The authenticity of the sender (that it’s really from GitHub)

GitHub does this by hashing the body of the request with a shared secret you provide when creating the webhook. It then sends that signature along with the request using the X-Hub-Signature-256 header.

🧩 Webhook Levels

Webhooks can be configured at three levels:

• Repository level – scoped to a single repo
• Organization level – applies to all repositories within an organization
• GitHub App level – used in GitHub Apps for deep integration across multiple repositories or organizations

For this example, I used an organization-level webhook so it applies to all repos in my org.

🔎 Signature Verification

To verify that the incoming request is really from GitHub, we need to:

1. Capture the raw request body before it’s parsed by Express.
2. Recompute the HMAC signature using the same secret.
3. Use a constant-time comparison to prevent timing attacks.

Here’s how I do it:

🔸 Express Middleware

We add a raw body parser to capture the exact payload:

app.use(express.json({
  verify: (req, _, buf) => {
    req.rawBody = buf;
  }
}));

This step is critical — HMAC must be calculated over the raw payload. If you parse it first, you’ll get a mismatch.

🔸 Signature Verifier (utils/verifier.js)

import crypto from 'crypto';
import { config } from './config.js';

export const verifySignature = (req)=>{
    const signature = req.headers['x-hub-signature-256'];
    if(!signature){
        return false;
    }
    const hmac = crypto.createHmac("sha-256", config.GIT_WEBHOOK_SECRET );
    hmac.update(req.rawBody);
    const expectedSignature = `sha256=${hmac.digest('hex')}`;
    return signature === expectedSignature;
}

📬 Sending Email Notifications

Once the signature is verified, I check if the action is "opened" on a PR, and then send an email.

I used Nodemailer with Gmail as the SMTP service. Since my Gmail account uses 2FA, I generated an App Password to authenticate.Use the app password without spaces.

🔸 Mailer (services/emailService.js)

const transporter = nodemailer.createTransport({
    service:"Gmail",
    auth:{
        user: config.EMAIL,
        pass: config.PASSWORD
    }
})

export  const sendPRrequestMail = (recipents, subject, text)=>{
    const mailOption = {
         from :config.EMAIL,
         to: recipents,
         subject: subject,
         text: text
    }
    return new Promise((resolve, reject)=>{
        transporter.sendMail(mailOption, (error, result)=>{
             if(error){
                 reject(error);
             }else{
                resolve(result);
             }
        })
    })

}

🚀 Exposing the Server for GitHub to Reach

To allow GitHub to reach my local server, I had two options:

1. Use a tunneling service like Ngrok
2. Deploy to a cloud provider. I chose to deploy to Render, which has a generous free tier and makes deployment super easy. Once deployed, I used the Render URL as the webhook endpoint in GitHub. ---

✅ Summary

• 🔐 We used HMAC with a shared secret to verify webhook authenticity.
• 📦 We used Nodemailer + Gmail to send email notifications.
• 🌐 We deployed our app to Render to make it accessible to GitHub.
• 🧠 And we learned that understanding webhooks at a low level is a great way to grow as a developer.

📂 Full Source Code

You can view the complete code for this project on GitHub:

👉 https://github.com/Mehakb78/git-prrequest-mailer
Feel free to clone it, experiment!