When you wire GitHub repository webhooks to an OpenClaw-style gateway on a remote Mac, most failures are boring infrastructure: the public URL is not the URL you think it is, the body you verify is not the body GitHub signed, or your process cold-starts while GitHub’s delivery worker already marks a timeout. This note is a reproducible tutorial for TLS ingress, HMAC headers, clock-safe timestamps, and the two loudest symptoms (401 loops and delivery timeouts). Keep the listener healthy with 2026 OpenClaw Gateway launchd Stability Handbook: doctor/status/logs Cross-Checklist, Port Binding & Dual LaunchAgent Conflicts — Remote Always-On Mac Field Steps, then align Actions-side disk behaviour using 2026 Multi-Mac Self-Hosted Runners & Parallel CI: GitHub Actions Cache, Local Persistent Disks, Race Locks, Full Disks, and Artifact Cleanup — Enterprise Pool FAQ so webhook-triggered jobs do not stall on I/O before they answer HTTP.
1. Lock a reproducible public callback path before you touch secrets
GitHub always calls you from the public internet. Whether you terminate TLS on nginx, a cloud load balancer, or a tunnel such as Cloudflare Tunnel / ngrok, write down hostname, path prefix, and whether the edge strips or adds headers. Reproduce with curl -v https://your-host/your-path from outside your LAN, not from the Mac itself, because loopback success hides hairpin NAT or wrong SNI. If a reverse proxy buffers bodies, your app must read the same raw bytes GitHub signed — otherwise every signature check fails even when the secret is correct. Keep one canonical URL in infra and paste the identical string into GitHub.
curl from the internet returns anything other than your gateway’s expected fast ACK path, fix ingress before you rotate webhook secrets again.2. Signature and timestamp verification that matches GitHub’s contract
GitHub signs the raw POST body with the webhook secret using HMAC-SHA256 in X-Hub-Signature-256. Hash the identical byte stream after TLS, compare with a constant-time routine, and reject malformed sha256= prefixes. Add a timestamp / skew policy: enable NTP on the Mac so valid signatures are not rejected beside time-bound bearer checks, and treat delivery IDs as idempotency keys so redeliveries after a timeout never double-apply side effects.
3. Repository settings that should match your gateway expectations
Use application/json unless you intentionally parse URL-encoded payloads. Keep SSL verification enabled and fix chains instead of disabling them. In Recent Deliveries, read the captured response — it is the fastest way to settle proxy debates. Rotate GitHub and gateway secrets in one window, then send a ping; partial rotations create deterministic 401s that look random until you open the delivery detail pane.
4. When the delivery log shows 401 but “the secret is right”
Layer the failure. First, ensure no global Authorization middleware sits in front of the webhook path. Second, look for Basic auth or CDN allowlists — mis-scoped rules still return 401. Third, never verify against a re-serialised JSON body; use the raw request bytes. Fourth, watch for double-prefix routes where the edge proxy 401s before traffic reaches the process you patched. Correlate one failing delivery ID with gateway access logs in the same millisecond window.
5. Timeouts: GitHub will not wait for your cold start
Deliveries expect a prompt HTTP response even when real work is asynchronous. If your gateway forks heavy work inline, GitHub may log a timeout while the Mac is still chewing. Queue long tasks, return 202 quickly when your API allows, and align proxy read/write timeouts with reality. Warm critical imports under launchd so the first post-reboot event is not a cold path. After any timeout, assume duplicate deliveries; make handlers idempotent on event IDs.
6. Pasteable triage checklist for on-call
- Outside-in
curlmatches the GitHub webhook URL character for character, including trailing slashes. - Body used for HMAC is the raw POST body; proxies are not transforming or decompressing unexpectedly.
- Mac clock within a few seconds of NTP; TLS to upstreams succeeds without manual clock fixes.
- No global auth middleware intercepts the webhook path; optional auth is scoped away.
- Handler returns quickly; heavy work is deferred and idempotent against redelivery.
Why a Mac mini-class gateway host still wins here
Webhooks punish flaky clocks, sleepy disks, and hosts that panic under light background load. Mac mini systems on Apple Silicon combine strong single-thread performance with very low idle power, which keeps TLS-terminated daemons economical compared to leaving a tower online for the same always-on role. They run the same native Unix networking stack, Homebrew-friendly layouts, and macOS hardening — Gatekeeper, SIP, and FileVault — that make internet-exposed automation less bespoke than on commodity PCs. If you are standardising OpenClaw-style gateways in 2026, anchor on hardware that stays quiet and predictable; compare dedicated regional nodes on the Macstripe home page when you outgrow a single lab machine.
If you want this webhook path running on the smoothest baseline hardware, Mac mini M4 is the most balanced starting point — compact, whisper-quiet, and efficient enough to hold TLS, signature verification, and adjacent CI triggers without turning your desk into a space heater. When you are ready to price a dedicated cloud Mac next to your self-hosted pool, open the Macstripe home page and map regions to your GitHub org’s latency profile.
