GitHub Webhooks and Integrations: Complete Guide

// Check GitHub for new events every 60 seconds
setInterval(async () => {
  const events = await fetch('https://api.github.com/repos/org/repo/events');
  // Process events...
}, 60000);

1. GitHub event occurs (push, PR opened, issue created)
2. GitHub makes HTTP POST to your server within seconds
3. Your server processes the event
4. Total round-trip: 1-3 seconds

X-GitHub-Event: push
X-GitHub-Delivery: abc123de-f456-7890-ghij-klmnopqrstuv
X-Hub-Signature-256: sha256=<hmac-signature>
Content-Type: application/json
User-Agent: GitHub-Hookshot/abc123

{
  "ref": "refs/heads/main",
  "before": "abc1234",
  "after": "def5678",
  "repository": {
    "id": 123456789,
    "name": "my-repo",
    "full_name": "my-org/my-repo",
    "private": false,
    "html_url": "https://github.com/my-org/my-repo"
  },
  "pusher": {
    "name": "alice",
    "email": "alice@example.com"
  },
  "commits": [
    {
      "id": "def5678",
      "message": "feat: add user authentication",
      "timestamp": "2026-04-18T10:30:00Z",
      "author": {
        "name": "Alice Smith",
        "email": "alice@example.com",
        "username": "alice"
      },
      "added": ["src/auth/login.ts"],
      "removed": [],
      "modified": ["src/app.ts", "package.json"]
    }
  ],
  "head_commit": { ... }
}

// webhooks/github.js — Express.js webhook handler
import express from 'express';
import crypto from 'crypto';

const router = express.Router();

function verifyGitHubSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// IMPORTANT: Use express.raw() for the webhook route, NOT express.json()
// You need the raw body bytes to verify the signature
router.post('/webhooks/github',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-hub-signature-256'];
    const event = req.headers['x-github-event'];
    const deliveryId = req.headers['x-github-delivery'];
    
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature' });
    }
    
    if (!verifyGitHubSignature(req.body, signature, process.env.GITHUB_WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Signature verified — safe to parse the payload
    const payload = JSON.parse(req.body.toString());
    
    // Always respond quickly (within 10 seconds) to avoid timeout
    res.status(200).json({ received: true, deliveryId });
    
    // Process the event asynchronously
    processWebhookEvent(event, payload).catch(err => {
      console.error('Webhook processing error:', err);
    });
  }
);

async function processWebhookEvent(event, payload) {
  switch (event) {
    case 'push':
      await handlePush(payload);
      break;
    case 'pull_request':
      await handlePullRequest(payload);
      break;
    case 'issues':
      await handleIssue(payload);
      break;
    case 'release':
      await handleRelease(payload);
      break;
    case 'ping':
      console.log('Webhook ping received, configuration successful');
      break;
    default:
      console.log(`Unhandled event type: ${event}`);
  }
}

async function handlePush(payload) {
  const branch = payload.ref.replace('refs/heads/', '');
  const pusher = payload.pusher.name;
  const commitCount = payload.commits.length;
  const headCommit = payload.head_commit;
  
  console.log(`Push to ${branch} by ${pusher}: ${commitCount} commits`);
  
  // Only deploy on push to main
  if (branch === 'main') {
    await triggerDeployment({
      commitSha: headCommit.id,
      commitMessage: headCommit.message,
      pusher,
    });
    
    await notifySlack(
      `🚀 Deploying ${commitCount} commit(s) to production\n` +
      `Branch: ${branch}\n` +
      `By: ${pusher}\n` +
      `Message: ${headCommit.message}`
    );
  }
}

async function handlePullRequest(payload) {
  const { action, pull_request, repository } = payload;
  const pr = pull_request;
  
  // action can be: opened, closed, reopened, edited, assigned,
  // review_requested, review_request_removed, labeled, unlabeled, synchronize
  
  if (action === 'opened') {
    await notifySlack(
      `📋 New PR #${pr.number}: ${pr.title}\n` +
      `By: ${pr.user.login}\n` +
      `Changes: +${pr.additions} -${pr.deletions} lines\n` +
      `URL: ${pr.html_url}`
    );
    
    // Auto-assign reviewers based on changed files (CODEOWNERS logic)
    await autoAssignReviewers(pr, repository);
  }
  
  if (action === 'closed' && pr.merged) {
    await recordMergeMetrics({
      prNumber: pr.number,
      timeToMerge: new Date(pr.merged_at) - new Date(pr.created_at),
      reviewCount: pr.reviews?.length ?? 0,
    });
  }
}

async function handleRelease(payload) {
  const { action, release } = payload;
  
  if (action === 'published') {
    console.log(`Release ${release.tag_name} published: ${release.name}`);
    
    await triggerProductionDeploy(release.tag_name);
    
    // Post release notes to Slack
    await notifySlack(
      `🎉 Release ${release.tag_name}: ${release.name}\n` +
      `${release.body.slice(0, 200)}...\n` +
      `Full notes: ${release.html_url}`
    );
  }
}

async function notifySlack(message) {
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: message,
      // For richer formatting use blocks:
      blocks: [
        {
          type: 'section',
          text: { type: 'mrkdwn', text: message },
        }
      ]
    }),
  });
}

import { Octokit } from '@octokit/rest';
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

async function handleIssue(payload) {
  const { action, issue, repository } = payload;
  
  if (action === 'opened') {
    // Auto-label based on issue title keywords
    const title = issue.title.toLowerCase();
    const labels = [];
    
    if (title.includes('bug') || title.includes('error') || title.includes('crash')) {
      labels.push('bug');
    }
    if (title.includes('feature') || title.includes('add') || title.includes('support')) {
      labels.push('enhancement');
    }
    
    if (labels.length > 0) {
      await octokit.issues.addLabels({
        owner: repository.owner.login,
        repo: repository.name,
        issue_number: issue.number,
        labels,
      });
    }
    
    // Welcome comment for first-time contributors
    const isFirstIssue = issue.author_association === 'FIRST_TIME_CONTRIBUTOR';
    if (isFirstIssue) {
      await octokit.issues.createComment({
        owner: repository.owner.login,
        repo: repository.name,
        issue_number: issue.number,
        body: `Welcome @${issue.user.login}! Thanks for opening your first issue. We'll review it shortly.`,
      });
    }
  }
}

1. Visit webhook.site
2. Copy your unique URL
3. Use it as the webhook payload URL in GitHub
4. View incoming payloads in real-time on the site

# Install ngrok, then:
ngrok http 3000

# ngrok gives you a public URL like:
# https://abc123.ngrok.io -> localhost:3000

# Use https://abc123.ngrok.io/webhooks/github as your GitHub webhook URL

gh webhook forward --repo=owner/repo --events=push,pull_request --url=http://localhost:3000/webhooks/github