GitHub Webhooks: A Practical Guide

What People Actually Use GitHub Webhooks For

GitHub webhooks are the connective tissue of most CI/CD setups. When you push to a branch, GitHub can instantly notify an external service — your build server, your deployment platform, your Slack channel — before you've even switched tabs. No polling, no cron jobs, no wondering whether the deploy kicked off. The push event fires, the webhook fires, and whatever needs to happen next happens.

The practical use cases break down roughly like this: triggering a test suite on every pull request, deploying to staging when something merges to main, posting a Slack message when a release is published, syncing GitHub issues to a project management tool like Linear or Jira, and notifying a security scanner every time new code is pushed. Any of these is a webhook.

The GitHub webhooks documentation covers the full picture, but the documentation is dense. This guide cuts straight to the patterns that come up in real projects.

Setting Up a Webhook in GitHub (Repository vs Organization)

There are two places you can create a GitHub webhook: at the repository level or at the organization level. A repository webhook only fires for events in that one repository. An organization webhook fires for events across all repositories in the org — useful when you want a single endpoint to handle events from dozens of repos without configuring each one individually.

For a repository webhook, go to your repo on GitHub, then Settings → Webhooks → Add webhook. For an organization webhook, go to your org page, then Settings → Webhooks → Add webhook. The configuration form is identical.

The Events You'll Actually Use

The full list of GitHub webhook events is long, but a handful cover the overwhelming majority of real-world use cases.

What a Push Event Actually Looks Like

The push event payload is rich, but there are four fields you'll reach for every time:

{
  "ref": "refs/heads/main",
  "commits": [
    {
      "id": "abc123def456",
      "message": "Fix the thing",
      "author": { "name": "Jane Dev", "email": "[email protected]" },
      "url": "https://github.com/org/repo/commit/abc123def456"
    }
  ],
  "repository": {
    "name": "my-repo",
    "full_name": "org/my-repo",
    "clone_url": "https://github.com/org/my-repo.git"
  },
  "pusher": {
    "name": "janedev",
    "email": "[email protected]"
  },
  "head_commit": {
    "id": "abc123def456",
    "message": "Fix the thing"
  }
}

The ref field tells you which branch was pushed to — it's always in the format refs/heads/branch-name. To get just the branch name you'll typically do ref.replace('refs/heads/', '').

Real GitHub push payloads are much larger — they include the full diff statistics, commit tree information, and more. When you're first wiring up a handler, it's useful to dump the full payload and explore it properly. JsonFormatter.ai is good for this — paste in the raw payload from the GitHub delivery log and you get a nicely formatted tree you can actually navigate.

Verifying the Signature (Don't Skip This)

GitHub signs every webhook delivery with HMAC-SHA256 using the secret you configured. The signature arrives in the X-Hub-Signature-256 header with a sha256= prefix. The full validation process is documented in GitHub's signature validation guide.

Your webhook URL is public. Anyone who knows it can POST to it. Signature verification is how you ensure the request actually came from GitHub and wasn't crafted by someone trying to trigger your CI pipeline or your deployment. Here's how to do it in Node.js:

import crypto from 'crypto';

function verifyGitHubSignature(rawBody, signature, secret) {
  const expectedSignature =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(rawBody) // rawBody must be a Buffer or string of raw bytes
      .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  const sigBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expectedSignature, 'utf8');

  if (sigBuffer.length !== expectedBuffer.length) return false;
  return crypto.timingSafeEqual(sigBuffer, expectedBuffer);
}

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

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

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

  // Now handle the event...
  res.status(200).send('OK');
});

Two things to notice: the body parser must preserve the raw bytes (use express.raw(), not express.json()), and the comparison uses crypto.timingSafeEqual rather than ===. The constant-time comparison prevents timing attacks where an attacker can infer the correct signature by measuring how long the comparison takes.

A Complete CI Trigger: Push to Main, Run a Build

Here's what a real push-triggered deployment handler looks like end to end. GitHub pushes to your endpoint, you verify the signature, check that it's the right branch, and kick off a build.

app.post('/webhooks/github', express.raw({ type: 'application/json' }), async (req, res) => {
  // Always acknowledge quickly
  res.status(200).send('OK');

  try {
    // Verify signature
    const signature = req.headers['x-hub-signature-256'];
    if (!verifyGitHubSignature(req.body, signature, process.env.GITHUB_WEBHOOK_SECRET)) {
      console.warn('Invalid GitHub signature — ignoring request');
      return;
    }

    const eventType = req.headers['x-github-event'];
    if (eventType !== 'push') return; // Only handle push events

    const payload = JSON.parse(req.body.toString());
    const branch = payload.ref.replace('refs/heads/', '');

    // Only deploy on pushes to main
    if (branch !== 'main') {
      console.log(`Push to ${branch} — skipping deploy`);
      return;
    }

    const commitSha = payload.head_commit.id;
    console.log(`Push to main by ${payload.pusher.name}, commit ${commitSha} — triggering build`);

    await triggerBuild({ branch, commitSha, repo: payload.repository.full_name });
  } catch (err) {
    console.error('GitHub webhook handler error:', err);
  }
});

The res.status(200).send('OK') goes at the top, before the async work. GitHub expects a response within 10 seconds and will mark the delivery as failed if it times out. Sending the response immediately and then doing the work asynchronously is the right pattern for anything that might take more than a second or two.

Handling pull_request Events Without Losing Your Mind

The pull_request event is fired for a lot of different things: when a PR is opened, when new commits are pushed to the branch (synchronize), when it's closed, when it's converted to a draft, when a label is added — the list is longer than you'd expect. The action field in the payload is how you tell them apart.

If you want to trigger something on new PRs and on new commits pushed to existing PRs, you care about action === 'opened' and action === 'synchronize'. For a staging deploy on merge specifically, you need to check for both action === 'closed' and payload.pull_request.merged === true. A closed PR that wasn't merged will also have action === 'closed' — you don't want to deploy that.

const eventType = req.headers['x-github-event'];
if (eventType !== 'pull_request') return;

const { action, pull_request: pr } = payload;

if (action === 'opened' || action === 'synchronize') {
  // New PR or new commits on existing PR — run tests
  await triggerTestRun({ branch: pr.head.ref, sha: pr.head.sha, prNumber: pr.number });
}

if (action === 'closed' && pr.merged === true) {
  // PR was merged (not just closed) — deploy to staging
  const targetBranch = pr.base.ref; // what branch was merged INTO
  if (targetBranch === 'main') {
    await deployToStaging({ sha: pr.merge_commit_sha });
  }
}

Notice pr.base.ref — that's the branch the PR was targeting. If your repo has multiple long-lived branches (main, staging, etc.), you'll want to check this before triggering a deploy.

Organization Webhooks and When to Use Them

Organization webhooks are scoped to the entire org — they receive events from every repository in the organization. The setup is the same as a repo webhook, but you need organization admin permissions to create one.

Use an org webhook when you have a single endpoint that handles events from many repositories — a centralized audit log, a deployment platform, a security scanner. The payload for org-level webhooks includes a repository field with the full name of the repo that triggered the event, so you can route accordingly.

Organization webhooks also support a few org-specific events that repo webhooks don't, like member (when someone is added or removed from the org) and organization (org settings changes). You can also create and manage webhooks programmatically using the GitHub REST API for webhooks — useful for tooling that provisions repos and needs to wire up webhooks automatically.

Mistakes That Will Cost You an Afternoon

Two mistakes come up constantly, and both are worth calling out explicitly rather than discovering them the hard way.

The first is not filtering by branch in push event handlers. When you subscribe to the push event, GitHub sends it for pushes to any branch — feature branches, release branches, hotfix branches, all of them. If you deploy on every push event without checking ref, you'll deploy every time anyone pushes a commit anywhere in the repository. The fix is one line: if (branch !== 'main') return;. It's easy to miss when you're first testing on a single-person repo where all pushes happen to be to main.

The second is not reading the action field on pull_request events. If you trigger a staging deploy every time a pull_request webhook fires, you'll deploy when someone adds a label to a PR, when someone requests a review, when someone edits the PR description. All of those fire the same pull_request event with different action values. Always check the action.

Keep Reading