GitHub Integration

Set up HookWatch to receive GitHub webhooks for repository events like pushes, pull requests, issues, and more.

Prerequisites

  • A HookWatch account
  • A GitHub repository with admin access (for repository webhooks) or organization admin access (for organization webhooks)
  • A server endpoint to process webhook payloads

Step 1: Create a HookWatch endpoint

  1. Go to your Endpoints page
  2. Click "Create Endpoint"
  3. Enter a name like "GitHub Webhooks"
  4. Enter your destination URL (where you want webhooks forwarded)
  5. Copy the generated webhook URL

Step 2: Configure GitHub webhook

For a repository:

  1. Go to your repository on GitHub
  2. Click Settings > Webhooks
  3. Click "Add webhook"
  4. Paste your HookWatch URL in the "Payload URL" field
  5. Set Content type to application/json
  6. Enter a Secret (you'll use this to verify webhooks)
  7. Select the events you want to trigger webhooks
  8. Click "Add webhook"

For an organization:

  1. Go to your organization settings on GitHub
  2. Click Webhooks in the sidebar
  3. Follow the same steps as above

Common events to subscribe to:

push - Code pushed to repository
pull_request - PR opened/closed/merged
issues - Issue created/updated
issue_comment - Comment on issue/PR
release - Release published
workflow_run - GitHub Actions status
deployment - Deployment created
star - Repository starred

Step 3: Verify webhooks on your server

GitHub signs webhook payloads with the secret you provided. HookWatch forwards the X-Hub-Signature-256 header so you can verify authenticity.

Node.js / Express 
const crypto = require('crypto');

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

app.post('/webhooks/github', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const secret = process.env.GITHUB_WEBHOOK_SECRET;

  if (!verifyGitHubSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-github-event'];
  const payload = JSON.parse(req.body);

  switch (event) {
    case 'push':
      console.log('Push to', payload.repository.full_name);
      break;
    case 'pull_request':
      console.log('PR', payload.action, payload.pull_request.title);
      break;
    // ... handle other events
  }

  res.json({received: true});
});

GitHub webhook headers

HookWatch forwards all GitHub headers. Here are the important ones:

HeaderDescription
X-GitHub-EventThe event type (push, pull_request, etc.)
X-GitHub-DeliveryUnique ID for the webhook delivery
X-Hub-Signature-256HMAC hex digest of the payload (SHA-256)
X-Hub-SignatureHMAC hex digest (SHA-1, deprecated)

Testing the integration

You can redeliver webhooks from the GitHub webhook settings:

  1. Go to your webhook settings in GitHub
  2. Click on "Recent Deliveries"
  3. Click on any delivery and then "Redeliver"
  4. Check your HookWatch Events page

Common issues

Signature verification fails

Make sure the secret in your code exactly matches what you entered in GitHub. The secret is case-sensitive and must not have extra whitespace.

Webhook shows as "failed" in GitHub

GitHub expects a 2xx response. If your server returns an error, GitHub marks the delivery as failed. Check your server logs and the HookWatch event details for more info.

Missing events

Verify that you've selected the correct events in GitHub webhook settings. Some events (like workflow_run) might not be enabled by default.