GitHub webhooks in TypeScript, on a URL that doesn't change
Webhooks are awkward to build because the other service calls you. GitHub needs a public URL, saved in your repo’s settings, and while you’re developing that URL has to reach your laptop.
A tunnel gets traffic to your laptop. But if the tunnel’s URL changes, GitHub carries on sending events to an address that no longer reaches you. You go back to the settings page, paste in the new URL, and try again. Over a project that lasts weeks, that keeps interrupting the work.
In this post we’ll build a small GitHub webhook endpoint in TypeScript and give it a localhost.run domain that stays the same. You set the webhook up in GitHub once. After that you can restart the server, the tunnel or the laptop as often as you like, and events still arrive.
You’ll need:
- Node.js 24 (or 22.18+), which runs TypeScript files directly
- An SSH key, and a localhost.run custom domain plan
- A GitHub repo you can change settings on
1. Write the endpoint
Make a project with no dependencies:
mkdir gh-webhook && cd gh-webhook
npm init -y
npm pkg set type=module
Create server.ts:
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";
const PORT = 3000;
const SECRET = process.env.WEBHOOK_SECRET ?? "";
if (!SECRET) throw new Error("set WEBHOOK_SECRET");
// GitHub signs the raw request body with your secret. Check the
// signature before trusting anything in the payload.
function verify(body: Buffer, signature: string | undefined): boolean {
if (!signature) return false;
const expected = "sha256=" + createHmac("sha256", SECRET).update(body).digest("hex");
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}
type PushEvent = {
ref: string;
repository: { full_name: string };
pusher: { name: string };
head_commit: { message: string } | null;
};
const server = createServer(async (req, res) => {
if (req.method !== "POST" || req.url !== "/webhook") {
res.writeHead(404).end();
return;
}
const chunks: Buffer[] = [];
for await (const chunk of req) chunks.push(chunk);
const body = Buffer.concat(chunks);
if (!verify(body, req.headers["x-hub-signature-256"] as string | undefined)) {
res.writeHead(401).end("bad signature");
return;
}
const event = req.headers["x-github-event"];
const payload = JSON.parse(body.toString("utf8"));
switch (event) {
case "ping":
console.log(`ping: ${payload.zen}`);
break;
case "push": {
const push = payload as PushEvent;
const message = push.head_commit?.message ?? "(no commits)";
console.log(`${push.pusher.name} pushed to ${push.repository.full_name} ${push.ref}: ${message}`);
break;
}
default:
console.log(`ignored ${event}`);
}
res.writeHead(204).end();
});
server.listen(PORT, () => console.log(`listening on http://localhost:${PORT}/webhook`));
Two details matter here:
- Verify the signature against the raw bytes. If you parse the JSON first and re-serialise it, the signature won’t match.
- Reply quickly. GitHub waits up to 10 seconds for a response. For slow work, reply first and do the work afterwards.
Make a secret and start the server in watch mode, so it restarts every time you save:
export WEBHOOK_SECRET=$(openssl rand -hex 32)
echo $WEBHOOK_SECRET # you'll paste this into GitHub
node --watch server.ts
2. Give it an address that doesn’t change
This is the step that makes the rest easy.
The free localhost.run plan changes its domain names periodically, to help prevent abuse. Reconnecting usually gets you the same address, but from time to time it changes. That’s fine for showing someone a page, but a webhook stores its URL in GitHub’s settings, so each change means updating them again. A paid plan gives you a domain that never changes.
- Sign in to the admin portal and add your SSH public key. Your key is how the tunnel knows it’s you.
- Add a domain. The quickest choice is a subdomain of
lhr.rocks, such asmy-hooks.lhr.rocks, which works straight away with no DNS setup. You can also use your own domain.
In a second terminal, connect the tunnel:
ssh -R my-hooks.lhr.rocks:80:localhost:3000 plan@localhost.run
Leave it running. https://my-hooks.lhr.rocks/webhook now reaches the server on
your laptop, with a valid HTTPS certificate. The terminal shows each request as
it arrives.
Run the same command tomorrow, or next month, and you get the same address.
3. Point GitHub at it
In your repo, go to Settings → Webhooks → Add webhook and set:
| Field | Value |
|---|---|
| Payload URL | https://my-hooks.lhr.rocks/webhook |
| Content type | application/json |
| Secret | the value of $WEBHOOK_SECRET |
| Events | Just the push event |
Save it. GitHub sends a ping straight away, and your server logs something
like:
ping: Design for failure.
Push a commit to the repo and you’ll see the push line too.
That’s the last time you need to open this settings page while you develop.
4. Develop against real events
Open the webhook in GitHub and click the Recent Deliveries tab. Every event GitHub sent is listed there, with the full request and your response, and each one has a Redeliver button.
So the loop is:
- Edit
server.tsand save.node --watchrestarts the server. - Click Redeliver on a delivery in GitHub.
- Read your terminal, and GitHub’s view of your response.
You don’t commit, deploy, or push to trigger an event. You also don’t touch the
webhook settings: restarting the server or the tunnel doesn’t change the
address, so GitHub always knows where to send events. The same real payload,
with a valid signature, can be replayed as many times as you need, and you can
use a debugger and console.log as usual.
Some tips:
- Stop whenever you like. Close the laptop and reconnect tomorrow with the
same
sshcommand. Events sent while you were away show as failed in Recent Deliveries, ready to redeliver. - Breaking things is fine. Return a 500 on purpose to see how GitHub reports it, then fix it and redeliver.
- Keep payloads as test fixtures. Copy a request body from Recent Deliveries into a file and use it in unit tests.
When it works
Deploy server.ts wherever it will live, then change the Payload URL in GitHub
to the production address. Keep the localhost.run webhook too, or add a second
one, so you can go back to working locally whenever the next change comes along.
The same approach works for Stripe, Slack, Twilio and any other service that calls you. A fixed address matters even more for some of them. In Stripe, for example, a new endpoint URL usually means a new endpoint, with a new signing secret to copy into your config. Run the endpoint locally, give it an address that doesn’t change, and replay real events against it until it works.