A lot of useful GitHub automation runs on machines that were never meant to be servers. A deploy script on a Mac mini under a desk. A bot on a Raspberry Pi. A build box in a home lab, behind a router that nobody wants to open a port on. A laptop that runs a few tools while you work and goes to sleep when you close the lid.
Webhooks assume the receiver is always up. GitHub sends a POST the moment something happens, and if your machine is asleep, rebooting, or between Wi-Fi networks, that event has nowhere to go. This post covers what GitHub does in that case, and a different way to set things up: let Hookbridge take the webhook, keep it, and let your machine collect it when it is ready.
What GitHub does when your endpoint is down
GitHub’s rules are short, and one of them surprises people:
- GitHub gives your server 10 seconds. From the GitHub docs: “If your server is down or takes longer than 10 seconds to respond, GitHub will record the delivery as a failure.”
- GitHub does not retry. The docs say it plainly: “GitHub does not automatically redeliver failed webhook deliveries.”
- You can redeliver by hand, or through the API, but only for deliveries from the past 3 days.
So if your machine misses a push event at 2 a.m., nothing will try again. You find out when you notice the deploy never happened, and then you dig through the repository’s webhook settings to click Redeliver. If you were away for four days, those deliveries are past the redelivery window.
The usual fixes are a cloud server that is always on, or a tunnel to your machine. Both work, but both mean running and paying for something whose only job is to sit and wait for HTTP requests.
A different shape: let the events wait for you
A Hookbridge pull endpoint flips who starts the conversation. GitHub sends to Hookbridge, which is always up. Hookbridge checks the signature and stores the event. Your machine asks Hookbridge for new events whenever it is awake.
GitHub
| POST, signed with your webhook secret
v
Hookbridge pull endpoint (ingest_url)
| signature checked, event stored
|
| ...your machine is asleep. The event waits...
|
v
Your machine wakes up and asks: "anything new?"
| GET events, process them, then ack
v
Done
From GitHub’s side, every delivery succeeds quickly, because Hookbridge answers it. Your machine only makes outbound HTTPS calls to the Hookbridge API, so there is no open port, no public IP, and no tunnel to keep alive.
Step 1: Create a pull endpoint that checks GitHub’s signature
When you give a GitHub webhook a secret, GitHub signs each delivery with HMAC-SHA256 over the request body and sends the result in the X-Hub-Signature-256 header as sha256=<hex>. Hookbridge can check that signature before it stores anything. It strips the sha256= prefix for you, and hex is the default encoding.
curl -X POST https://api.hookbridge.io/v1/pull-endpoints \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GitHub events for the home lab",
"verify_hmac": true,
"hmac_header_name": "X-Hub-Signature-256",
"hmac_secret": "YOUR_GITHUB_WEBHOOK_SECRET",
"event_type_source": "header",
"event_type_path": "X-GitHub-Event"
}'
The last two fields tell Hookbridge to read the event type from GitHub’s X-GitHub-Event header. That lets you filter later, for example to pull only push events.
The response includes an ingest_url and a secret_token. They are only shown once, so save them somewhere safe. Treat the ingest_url like a password, because the secret part of the path is what lets a request in.
Step 2: Point GitHub at the ingest URL
In your repository (or organization), go to Settings, then Webhooks, then Add webhook:
- Set the payload URL to your
ingest_url. - Set the content type to
application/json. - Set the secret to the same value you used for
hmac_secret. - Pick the events you care about.
GitHub sends a ping event when you save. Open the Pull tab in the Hookbridge console and you should see it stored. If it shows up under Rejections with the reason hmac_failed, the secret in GitHub and the hmac_secret in Hookbridge do not match.
Step 3: Collect events when your machine is awake
Here is a small worker that uses the Hookbridge Python SDK (pip install hookbridge). Run it from cron, from a launchd job on a Mac, or in a loop. It works the same whether the machine was asleep for a minute or a whole weekend.
import os
from hookbridge import HookBridge
client = HookBridge(api_key=os.environ["HOOKBRIDGE_API_KEY"])
ENDPOINT_ID = os.environ["HOOKBRIDGE_PULL_ENDPOINT_ID"]
def header(headers, name):
# Header names may come back in any case.
for key, value in (headers or {}).items():
if key.lower() == name.lower():
return value
return None
def handle(event):
gh_event = header(event.headers, "X-GitHub-Event")
delivery_id = header(event.headers, "X-GitHub-Delivery")
payload = event.payload
# Skip work you have already done. Store delivery_id somewhere
# with a unique constraint and check it first.
if gh_event == "push" and payload["ref"] == "refs/heads/main":
print(f"deploying {payload['after']} (delivery {delivery_id})")
# run your deploy here
def drain(status):
cursor = None
while True:
page = client.list_pull_events(
ENDPOINT_ID, status=status, limit=100, cursor=cursor
)
done = []
for summary in page.events:
event = client.get_pull_event(ENDPOINT_ID, summary.id)
handle(event)
done.append(summary.id)
if done:
client.ack_pull_events(ENDPOINT_ID, done)
if not page.has_more:
return
cursor = page.next_cursor
# Finish anything a previous run fetched but never acked, then get new events.
drain("fetched")
drain("stored")
A few things are going on here.
Events move through three states. They start as stored. Fetching one by ID marks it fetched. Acking it marks it delivered. The list call returns only stored events unless you ask for another status, so each run picks up what is new.
The worker acks only after handle finishes. If the machine dies halfway through a batch, those events stay fetched. The drain("fetched") line at the start of each run picks them up again. That means an event can be handled twice, which is why the handler should skip delivery IDs it has already seen. GitHub’s X-GitHub-Delivery header is a unique ID for each delivery, and Hookbridge returns the original headers with every event, so you have it right there.
Events come back oldest first. If three pushes landed while your machine was off, you process them in the order GitHub sent them.
If you only care about some events, add event_type=push to the list call. That works because of the event_type_source setting from Step 1.
When this setup fits, and when it does not
This works well when a delay of a few minutes is fine and the machine doing the work is not a server. That covers deploy scripts, home lab automation, personal bots, and build boxes behind a firewall that only allows outbound traffic.
It is a worse fit when something must happen within a second or two of the event. Your machine only sees events as often as it polls. If you need instant reactions and you have a server that is always up, a Hookbridge inbound endpoint is the better choice. It forwards each event to your URL right away and retries with backoff when your server fails.
Troubleshooting checklist
- Nothing shows up in the Pull tab. Check that the GitHub payload URL is the exact
ingest_url, and look in the repository’s webhook Recent Deliveries list for the response GitHub got. - Events show up under Rejections with
hmac_failed. The secret in GitHub does not matchhmac_secret. Set both to the same value. - The worker sees no events, but the console shows them. They are probably already
fetched. Run the worker withstatus=fetched, orstatus=allto see everything. - A deploy ran twice. Store
X-GitHub-Deliverywith a unique constraint and skip IDs you have seen.
Try it
If GitHub is sending webhooks to a machine that sleeps, reboots, or moves between networks, let Hookbridge hold them. Create a free Hookbridge account, add a pull endpoint, and see the pull endpoints page for more examples.