GitHub webhooks on localhost

Point a repository's or organization's webhook at a handler on your computer, watch each delivery in the inspector, and replay it while you fix the handler. The examples use a handler at http://localhost:3000/webhooks/github and the hostname hooks.yourhost.com.

1. Share the handler

teitunnel share 3000 --on hooks.yourhost.com --watch "/webhooks/*"

2. Add the webhook in GitHub

In the repository, Settings ▸ Webhooks ▸ Add webhook:

• Payload URL: https://hooks.yourhost.com/webhooks/github
• Content type: application/json
• Secret: a long random string your handler also knows.
• Keep SSL verification on.

GitHub sends a ping event straight away. Save the same secret in Teitunnel so the inspector checks each delivery:

teitunnel inbox secret hooks.yourhost.com github  # asks for the secret

3. Read a delivery

Each delivery carries:

X-Hub-Signature (SHA-1) is only there for old handlers; check X-Hub-Signature-256. GitHub's signature has no timestamp, so a plain replay still verifies.

teitunnel traffic ls --path /webhooks/github --last 5
teitunnel traffic replay 7f3a

GitHub's own Recent Deliveries can Redeliver anything from the past 3 days.

Things GitHub is strict about

• Answer within 10 seconds with a 2xx, then do the work.
• The raw body. Compute the signature over the bytes as received, before parsing.
• Payloads up to 25 MB. GitHub doesn't send larger ones at all.

While your computer is off

GitHub doesn't retry a failed delivery by itself. Anything sent while your computer is off is lost unless you redeliver it by hand. A webhook inbox keeps those deliveries on your Cloudflare account and delivers them in order when you're back, keeping only correctly signed ones:

teitunnel inbox add hooks.yourhost.com /webhooks/github --verify github

Related