GitHub Webhook Testing

GitHub webhooks are essential for CI/CD, automation, and monitoring. This guide shows how to test and debug GitHub webhooks using Echopoint.

Setting Up GitHub Webhooks

Step 1: Create Webhook Endpoint

1. Visit Echopoint
2. Click "Create Webhook"
3. Copy your unique webhook URL:

   https://echo.echopoint.dev/hook/your-unique-id
   

Step 2: Configure GitHub Repository

1. Go to your GitHub repository
2. Navigate to Settings → Webhooks
3. Click Add webhook
4. Paste your Echopoint URL in Payload URL
5. Set Content type to application/json
6. Choose events you want to monitor

Common GitHub Events

Push Events

Triggered when code is pushed to the repository:

{
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "repository": {
    "name": "my-repo",
    "full_name": "user/my-repo"
  },
  "pusher": {
    "name": "developer",
    "email": "[email protected]"
  },
  "commits": [
    {
      "id": "def456...",
      "message": "Fix bug in authentication",
      "author": {
        "name": "Developer",
        "email": "[email protected]"
      }
    }
  ]
}

Pull Request Events

Triggered on PR creation, updates, or merges:

{
  "action": "opened",
  "number": 123,
  "pull_request": {
    "title": "Add new feature",
    "body": "This PR adds a new authentication method",
    "state": "open",
    "user": {
      "login": "developer"
    },
    "head": {
      "ref": "feature-branch"
    },
    "base": {
      "ref": "main"
    }
  }
}

Issue Events

Triggered when issues are created or updated:

{
  "action": "opened",
  "issue": {
    "number": 456,
    "title": "Bug in login system",
    "body": "Users can't login after recent update",
    "state": "open",
    "user": {
      "login": "user123"
    },
    "labels": [
      {
        "name": "bug",
        "color": "d73a4a"
      }
    ]
  }
}

Testing Webhook Delivery

Verify Webhook Signature

GitHub signs webhooks with HMAC SHA-256. Check the signature:

const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex')
  
  const expectedBuffer = Buffer.from(`sha256=${expectedSignature}`, 'utf8')
  const actualBuffer = Buffer.from(signature, 'utf8')
  
  return crypto.timingSafeEqual(expectedBuffer, actualBuffer)
}

Handle Different Event Types

Filter webhooks by event type using headers:

app.post('/webhook', (req, res) => {
  const event = req.headers['x-github-event']
  
  switch (event) {
    case 'push':
      handlePushEvent(req.body)
      break
    case 'pull_request':
      handlePullRequestEvent(req.body)
      break
    case 'issues':
      handleIssueEvent(req.body)
      break
    default:
      console.log(`Unhandled event: ${event}`)
  }
  
  res.status(200).send('OK')
})

Debugging Common Issues

Webhook Not Receiving Requests

1. Check Echopoint dashboard - Are requests appearing?
2. Verify URL - Make sure GitHub has correct webhook URL
3. Check repository settings - Ensure webhook is active
4. Test with curl:

   curl -X POST https://echo.echopoint.dev/hook/your-id \
     -H "Content-Type: application/json" \
     -d '{"test": "payload"}'
   

Invalid Signature Errors

1. Check secret - Ensure webhook secret matches your code
2. Verify algorithm - GitHub uses HMAC SHA-256
3. Raw payload - Use raw request body, not parsed JSON
4. Header format - Signature is in X-Hub-Signature-256 header

Missing Events

1. Event selection - Check which events are enabled in GitHub
2. Repository access - Ensure webhook has proper permissions
3. Rate limiting - GitHub may throttle webhook delivery
4. Payload size - Large payloads might be truncated

Advanced Use Cases

CI/CD Pipeline

Trigger builds on push events:

# GitHub Actions workflow
name: Build on Push
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build project
        run: npm run build

Automated Issue Management

Auto-label issues based on content:

function handleIssueEvent(payload) {
  if (payload.action === 'opened') {
    const { title, body } = payload.issue
    
    // Auto-label bugs
    if (title.toLowerCase().includes('bug') || 
        body.toLowerCase().includes('error')) {
      addLabelToIssue(payload.issue.number, 'bug')
    }
    
    // Auto-label features
    if (title.toLowerCase().includes('feature') ||
        title.toLowerCase().includes('enhancement')) {
      addLabelToIssue(payload.issue.number, 'enhancement')
    }
  }
}

Deployment Notifications

Notify team on successful deployments:

function handlePushEvent(payload) {
  if (payload.ref === 'refs/heads/main') {
    // Trigger deployment
    deployToProduction()
    
    // Notify team
    sendSlackNotification({
      channel: '#deployments',
      message: `🚀 Deployed ${payload.commits.length} commits to production`
    })
  }
}

Best Practices

Security

• Always verify signatures - Don't trust unsigned webhooks
• Use HTTPS only - Never expose webhook endpoints over HTTP
• Validate payloads - Check required fields before processing
• Rate limiting - Implement protection against webhook spam

Reliability

• Return quickly - GitHub expects responses within 10 seconds
• Handle retries - GitHub retries failed webhooks
• Log everything - Keep detailed logs for debugging
• Monitor health - Track webhook success rates

Performance

• Async processing - Handle heavy work in background jobs
• Batch operations - Group multiple webhook events when possible
• Cache data - Avoid unnecessary API calls
• Scale horizontally - Use load balancers for high volume

Monitoring with Echopoint

Use Echopoint's analytics to monitor webhook health:

• Success rate - Track delivery success over time
• Response times - Monitor webhook processing speed
• Error patterns - Identify common failure scenarios
• Traffic patterns - Understand when webhooks are most active

Troubleshooting Tips

1. Start simple - Test with basic events first
2. Use Echopoint filters - Search for specific event types
3. Check GitHub delivery logs - Repository settings show delivery attempts
4. Test locally - Use tools like ngrok to test webhook handling code
5. Read documentation - GitHub's webhook docs are comprehensive

Next Steps

• Webhook security best practices
• Processing webhook payloads
• Stripe webhook testing
• Discord bot webhooks

Happy webhook testing! 🎣