GitHub Webhooks Local Development: Test Push, PR, and Issue Events

Building a CI/CD tool? A GitHub bot? A deployment system? You'll need to handle GitHub webhooks. Push events, pull request updates, issue comments — GitHub sends webhooks for almost everything.

The challenge is testing them locally. You can't exactly ask your team to "push some commits so I can debug this webhook handler."

Why GitHub Webhooks Are Different

GitHub webhooks have some unique characteristics:

• Event variety — Over 40 different event types, each with different payloads
• Large payloads — Push events can include full commit data, diffs, and file changes
• Signature verification — GitHub signs webhooks with HMAC-SHA256
• Hard to trigger — You can't easily create a "test push" without actually pushing

Setting Up GitHub Webhooks for Local Development

Here's how to set up a workflow that doesn't require constant pushing:

https://hookreplay.dev/hook/your-unique-id

$ npx hookreplay

● hookreplay> connect
✓ Connected! Waiting for replay requests...

Common GitHub Webhook Events

Here are the events you'll most likely need to handle:

Verifying GitHub Signatures

GitHub signs webhooks using HMAC-SHA256 with your webhook secret. The signature is in the X-Hub-Signature-256 header.

const crypto = require('crypto');

function verifyGitHubSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

During development, you can skip verification or use the same secret that GitHub is using to sign the webhooks.

Testing Different Scenarios

With payload editing, you can test scenarios that are hard to create naturally:

• Force push — Set forced: true in the push payload
• PR from fork — Modify the head repository details
• Deleted branch — Set deleted: true
• Large commit batch — Add more commits to the array
• Specific file changes — Edit the added, modified, removed arrays

Instead of creating real scenarios in your repo (which pollutes your git history), just edit the payload and replay.

Building GitHub Bots

If you're building a bot that responds to comments (like /deploy commands), capture-and-replay is essential. You don't want to spam your PRs with test comments.

1. Capture one real issue_comment event
2. Edit the comment body to test different commands
3. Replay until your bot handles all cases correctly

Your PR stays clean, your bot gets tested.

Summary

GitHub webhook development doesn't have to mean constantly pushing commits or creating PRs. Capture the events once, then:

• Replay them unlimited times while debugging
• Edit payloads to test edge cases
• Build and test bots without spamming your repos
• Keep your git history clean

Focus on writing your webhook handler, not on creating test events.