~/guides/WEBHOOK.md

Guides / Build apps

A webhook is a doorbell: wire a GitHub webhook with 3 Claude Code prompts, then test it locally with smee.io

Stop asking "anything new?" every minute: GitHub pushes events to your app. Three prompts, GitHub settings, signature checks, the 10-second rule, smee.io.

Lots of apps ask every minute: "anything new?" It's like walking to the mailbox again and again, and it's usually empty. A webhook flips that: you give GitHub a URL once, and the moment something happens, it sends the data to you. This is the full version of my WEBHOOK reel: how the little inbox app running on my computer works, the three things to tell Claude Code (copy them), what to fill in on GitHub, and how to test it on your own machine with smee.io. Everything about GitHub follows the official docs, which I checked on 10 November 2026.

01The result first: someone opens an issue on GitHub, my app gets it right away

My webhook inbox page: issues.opened #42 at the top, latency 891 ms, signature checked
The small app on my computer (real screen): this event took 891 ms from sending to arriving.

The inbox is a tiny Node program that only uses built-in modules, with nothing to install. Events come in through smee.io, the app checks the signature, keeps the event only if it matches, and the page updates live. It's the same path a real GitHub webhook takes; the only difference is that I sent the test events myself, in GitHub's format.

  1. How a webhook differs from asking every minute (in GitHub's own words).
  2. The three prompts for Claude Code, ready to copy.
  3. The Payload URL and Secret you fill in on your GitHub repo.
  4. Testing on your own computer with smee.io, plus GitHub's one-click redeliver.

02What a webhook is: stop checking the mailbox, wait for the doorbell

Reel frame: a paper door and doorbell next to GitHub Docs' About webhooks, "as opposed to polling an API" in red
Reel frame: GitHub's docs say a webhook delivers data as things happen, as opposed to polling an API.

Asking again and again is called polling: your program calls an API every so often to see if there's anything new. Most of those calls come back empty, and asking too often can run you into the API's rate limit.

A webhook is the doorbell. You tell GitHub once which events you care about and which URL to send them to. After that, every time someone opens an issue, pushes code or opens a PR, GitHub sends an HTTP request with that event's data to your URL. Once your app has it, it can post to Discord, redeploy, write to a database, whatever you need.

03Prompt 1: open a /webhook URL that receives GitHub events

Open Claude Code in your project folder and paste this. Swap the parts in [] for your own setup:

Prompt 1 (paste into Claude Code)
Write a small app in [Node / Python / your language] (port [3000]): open a /webhook URL that receives GitHub [issues] events, and a home page that lists incoming events live (event type, title, time received).
GitHub Docs, Creating webhooks: the Payload URL and Secret steps
GitHub Docs: the steps for creating a repository webhook.
  1. In your repo, go to Settings → Webhooks → Add webhook.
  2. Payload URL: your URL (for local testing, the smee.io URL from below).
  3. Content type: application/json, so the event arrives as the body of the POST.
  4. Secret: a long random string. Prompt 2 uses it.
  5. Under "Which events", tick only what you need, for example Issues. GitHub recommends subscribing to as few events as possible.

04Prompt 2: check the signature with your secret, block the fakes

Your /webhook URL is public, so anyone can pretend to be GitHub. GitHub uses the secret you set to sign every delivery and puts the signature in the X-Hub-Signature-256 header. Your app computes it again with the same secret and only accepts the request if they match.

Prompt 2 (paste into Claude Code)
Verify every request's X-Hub-Signature-256 with my secret (HMAC SHA-256 over the raw body, constant-time comparison), and answer 401 if it doesn't match. Read the secret from the environment variable [WEBHOOK_SECRET]; don't hard-code it.
GitHub Docs, Validating webhook deliveries: the signature goes in the X-Hub-Signature-256 header
GitHub Docs: how the signature is computed and which header carries it.
The inbox app's top-right corner reads 連線中・已擋掉 1 個假事件 (connected, 1 fake event blocked)
My test (real screen): a request signed with the wrong secret got a 401: "1 fake event blocked".

05Prompt 3: answer first, do the work after

GitHub waits only 10 seconds. If your server doesn't answer with a 2XX within that time, GitHub drops the connection and counts the delivery as failed. So answer "got it" first and do the real work (emails, deploys, database writes) afterwards.

Prompt 3 (paste into Claude Code)
When a webhook arrives, answer 202 right away and process it in the background, so GitHub never waits more than 10 seconds. Before processing, check X-GitHub-Event and the payload's action; only handle [issues.opened] and ignore the rest.
GitHub Docs best practices: the Respond within 10 seconds section
GitHub Docs: Respond within 10 seconds.

Two more best practices worth adding to the same prompt: check the event type and action before processing (GitHub keeps adding new events), and use the X-GitHub-Delivery header to recognise the same delivery so it isn't processed twice.

06Test on your own computer: smee.io forwards events to localhost

GitHub can't reach localhost on your computer, so GitHub's testing guide uses smee.io as a relay: GitHub sends to your smee.io URL, and the smee client passes it on to the app on your machine. That's exactly how the test in my reel ran.

  1. Open smee.io, click Start a new channel and copy the Webhook Proxy URL.
  2. Put that URL in your GitHub webhook's Payload URL.
  3. Start your app on your computer (for example on port 3000).
  4. In a second terminal, install the smee client and start forwarding (commands below).
  5. Open an issue in the repo and check that both the smee.io page and your app show it.
smee forwarding (paste into a terminal)
npm install --global smee-client
smee --url [your smee.io URL] --path /webhook --port [3000]
smee.io's Webhook Deliveries page listing three issues events
My test (real screen): the three events on the smee.io page. The app kept two and blocked the fake one.

Changed your code and want to test again? You don't need a new issue: in the repo go to Settings → Webhooks → your webhook → Recent deliveries, open a delivery and click Redeliver. The docs say you can redeliver deliveries from the past 3 days if you have admin access to the repo, and that GitHub never redelivers failed deliveries on its own.

07Watch out for

  1. Keep the secret out of your code and out of GitHub; use an environment variable. Don't put passwords or API keys in the URL either (the docs warn about this).
  2. Use an HTTPS URL in production. GitHub verifies SSL certificates by default and recommends leaving that on.
  3. smee.io is a testing relay: anyone with the channel URL can see what goes through it. In production, point the webhook at your own server.
  4. The same event can arrive again (when you click Redeliver, or when your server didn't answer). Check X-GitHub-Delivery before processing.
  5. The events in the reel are test events I sent in GitHub's format, and the latency is one measurement through smee.io, not GitHub's speed.

Sources

Related guides