Test GitHub Webhooks Locally

From a stuck handler to a live GitHub delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL — something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3In the repo go to Settings → Webhooks → Add webhook and set the Payload URL to your LocalCan URL with your path, e.g. https://your-app-12.localcan.dev/webhook. Set Content type to application/json, type a high-entropy string into Secret (this is the key GitHub will sign with — there is no fixed format or prefix), then pick the events to send. For an org hook use Org Settings → Webhooks.
4. 4GitHub sends a ping the moment you save. To re-fire later, open the webhook → Recent deliveries → click a delivery’s GUID → Redeliver. GitHub does not auto-retry failures and only keeps the last 3 days of deliveries. For a live local loop, gh webhook forward --repo=OWNER/REPO --events=push --url=http://localhost:3000/webhook relays real events to your machine.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body — expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

X-Hub-Signature-256

Algorithm

HMAC-SHA256, lowercase hex (legacy X-Hub-Signature is HMAC-SHA1)

What's signed

GitHub signs the raw request body bytes with your webhook secret and sends sha256= + the lowercase hex digest — no timestamp or delivery id is mixed in, just the body. Critical: with Content type application/x-www-form-urlencoded the body is payload=<urlencoded JSON>, so you must HMAC those exact bytes, not the inner JSON. Parse or re-serialize the body before hashing and the signature can never match.

Secret

A secret you set on the webhook (Settings → Webhooks → Secret, or config.secret via the REST API). GitHub does not issue it — there is no prefix or fixed length, just "a random string of text with high entropy". It is optional: if you never set one, deliveries are unsigned and X-Hub-Signature-256 is absent entirely (not "wrong").

import express from 'express'
import crypto from 'node:crypto'

const secret = process.env.GITHUB_WEBHOOK_SECRET // the string you typed into the Secret field

const app = express()

// GitHub signs the RAW body. Capture the exact bytes BEFORE any JSON parser.
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-hub-signature-256'] // 'sha256=<hex>' — absent if no secret set
  if (!sig) {
    // No secret configured on the webhook → no header. Reject cleanly, do not throw.
    return res.status(401).send('signature missing')
  }

  // req.body is a Buffer (the raw bytes). HMAC those, not a re-stringified object.
  const digest = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex')

  const a = Buffer.from(sig)
  const b = Buffer.from(digest)
  // timingSafeEqual throws if lengths differ — guard, and never use plain ==.
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('signature mismatch')
  }

  const event = req.headers['x-github-event'] // 'ping' on first save, then 'push', etc.
  if (event === 'ping') return res.status(200).send('pong')

  const payload = JSON.parse(req.body.toString('utf8'))
  // handle push / pull_request / ...
  res.status(202).send('ok')
})