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 (there is no prefix or format), then pick the events to send. For an org hook use the organization’s Settings → Webhooks.
4. 4GitHub sends a ping the moment you save. To send it again without touching the config, call POST /repos/{owner}/{repo}/hooks/{hook_id}/pings. To re-send a real event, open the webhook → Recent deliveries → click a delivery’s GUID → Redeliver. That works for deliveries from the past 3 days, and GitHub never retries a failure by itself.
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.

GitHub saysurl is not supported because it isn't reachable over the public Internet (localhost)

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. 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. Whether a re-serialized object still matches depends on your language’s serializer, so verify the bytes you received.

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')) // Content type application/json
  // handle push / pull_request / ...
  res.status(202).send('ok')
})

app.listen(3000)

A replayed capture verifies for as long as LocalCan holds it. GitHub signs the body and nothing else (no timestamp, no tolerance window), and replayed ping, push and issues deliveries all passed the same check as the originals. The inspector keeps the latest exchanges in memory (250 by default) and clears them when the daemon restarts, so use Copy as cURL (bodies up to 1 MB) to keep a delivery you want to reuse next week.