localhost.run blog

GitHub webhooks in TypeScript, on a URL that doesn't change

· webhooks, typescript, github, use cases

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:

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:

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.

  1. Sign in to the admin portal and add your SSH public key. Your key is how the tunnel knows it’s you.
  2. Add a domain. The quickest choice is a subdomain of lhr.rocks, such as my-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:

FieldValue
Payload URLhttps://my-hooks.lhr.rocks/webhook
Content typeapplication/json
Secretthe value of $WEBHOOK_SECRET
EventsJust 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:

  1. Edit server.ts and save. node --watch restarts the server.
  2. Click Redeliver on a delivery in GitHub.
  3. 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:

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.