2026 OpenClaw Webhooks Inbound for GitHub/GitLab CI: Shared Secrets, Gateway Routing & Rate Limits, Reproducible Deploy on a Dedicated Remote Mac over SSH — 401/413/Timeout FAQ
CI systems speak HTTP. When you want GitHub Actions or GitLab CI to nudge an OpenClaw-compatible gateway on a headless Mac, the boring parts—shared secrets, reverse-proxy path routing, gateway throttles, and payload size—decide whether production is quiet or a pager festival. This runbook maps inbound webhooks to a reproducible SSH deployment on dedicated metal and ends with a triage table for 401, 413, and timeouts.
TL;DR — Key Takeaways
Bottom line: Treat the webhook URL as a capability URL: authenticate every request, keep payloads small, and let the gateway enforce back-pressure before your worker touches models or disk.
- GitHub: verify
X-Hub-Signature-256(HMAC-SHA256 of the raw body) with a secret stored only in CI and on the verifier. - GitLab: send
X-Gitlab-Token(or pipeline token via variable) and reject if missing—do not rely on "security through obscurity" URL paths alone. - Gateway: one external hostname, path prefixes per environment (
/hooks/prod/...), and explicit rate limits so a runaway pipeline cannot stampede local inference. - Mac worker: pin versions (
openclaw, Node, brew formulae), keep config in git, restart vialaunchd, and smoke-test over SSH the same way CI will hit HTTPS.
For how Apple and CI credentials intersect on a headless runner, see 2026 Dedicated Remote Mac CI: App Store Connect API (.p8) & Fastlane — Key Storage & Pipeline Injection on SSH Headless Macs. For gateway upgrades and timeout alignment after a version bump, use 2026 OpenClaw v2026.4.14 Post-Upgrade Acceptance: Gateway Tools Patch & Ollama Timeout Fix on a Dedicated Remote Mac over SSH.
1. Reference Architecture: CI → HTTPS → Gateway → Worker
A typical 2026 layout looks like this: GitHub Actions or GitLab CI runs on shared infrastructure and calls your HTTPS endpoint. That endpoint should terminate TLS at a reverse proxy or edge (Cloudflare, Tailscale Serve, or a cloud LB), then forward to a local listener bound to 127.0.0.1 on the Mac. The OpenClaw-style gateway validates the webhook, normalizes JSON, and hands work to a process that may call models, tools, or shell automation.
Keeping the public surface at the proxy lets you rotate certificates, add WAF rules, and apply per-path rate limits without redeploying the daemon for every CI tweak.
2. Shared Secrets: GitHub HMAC vs GitLab Token Headers
2.1 GitHub (X-Hub-Signature-256)
GitHub signs the raw POST body with your webhook secret. Your verifier must hash the identical bytes (no pretty-printed JSON) and compare using a constant-time compare. Store the secret in GitHub as a repository or organization secret; on the Mac side, load it from an environment file readable only by the service user—not world-readable home directories.
2.2 GitLab (X-Gitlab-Token)
GitLab can send a static token header for pipeline or project webhooks. Treat it like a password: rotate on schedule, scope it to the narrowest project, and log verification failures without echoing the token. If you trigger via curl from .gitlab-ci.yml, inject the token from a masked CI variable and keep job logs from printing the URL.
3. Gateway Routing, Path Prefixes, and Multi-Environment Safety
Use explicit path namespaces: /hooks/ci/prod, /hooks/ci/staging. Map each to a distinct internal port or Unix socket so a staging bug cannot enqueue production work. At the edge, attach different WAF or rate-limit profiles: production gets stricter burst control; staging can allow more replays for debugging.
If you terminate TLS on the Mac (not always recommended), still keep separate listener configs per environment file—never "one config, two meanings" toggled by a query string.
4. Rate Limiting: Protecting the Gateway from CI Storms
CI can accidentally fan out: matrix jobs, retries, and manual re-runs may deliver dozens of POSTs per minute. Configure reverse-proxy or gateway-level limits (requests per second and concurrent connections) so a backlog shows up as HTTP 429 with Retry-After, not as wedged local queues. Pair numeric limits with alert thresholds on 429 ratio so you notice misconfigured workflows before users do.
5. Reproducible Deployment on a Dedicated Remote Mac (SSH)
Reproducibility is the difference between "works on my machine" and "works every Tuesday at 3am." On an exclusive Mac you control:
- Versions: pin
openclawCLI, gateway package, and Node runtime; record them in a smallversions.lockfile next to your infra repo. - Config: keep listener address, webhook routes, and environment variables in git; deploy with
rsyncor a tiny Makefile target over SSH. - Process model: use
launchdplists withStandardOutPath/StandardErrorPathso CI-triggered failures leave an audit trail. - Smoke tests: from the CI job (or a manual gate), POST a signed dummy payload against the same public URL the webhook uses—if TLS, path, or headers drift, you catch it before merging.
6. FAQ Matrix: 401, 413, and Timeouts
| Symptom | Likely cause | What to check first |
|---|---|---|
401 Unauthorized |
Missing/wrong HMAC or token; clock skew rare for HMAC but common for JWT edges. | Log the presence of X-Hub-Signature-256 / X-Gitlab-Token (never log values). Recompute HMAC on the raw body. Confirm CI variable matches Mac-side secret. |
413 Payload Too Large |
CI posted an oversized JSON (artifacts embedded by mistake) or proxy body limit lower than GitLab/GitHub defaults. | Strip binaries from webhook payloads—send URLs instead. Raise client_max_body_size (nginx) or equivalent only if you must, and keep a hard cap in the app. |
Client timeout / 504 upstream |
Worker blocked on model I/O; CI HTTP step shorter than gateway processing; proxy idle timeout. | Make the webhook handler return 202 Accepted quickly and process async. Align GitHub --max-time / GitLab curl timeouts with proxy keep-alive. See gateway timeout tuning in the post-upgrade FAQ linked above. |
Why a Mac mini Is a Strong Home for Webhook Workers
Webhook gateways are long-lived services: they should survive weeks without manual restarts, tolerate bursts from CI, and stay quiet on a desk. A Mac mini with Apple Silicon delivers very low idle power (often only a few watts), silent cooling, and macOS stability that pairs well with unattended launchd jobs. You get a native Unix userland for SSH automation, Homebrew for proxy helpers, and Apple’s defense-in-depth stack—Gatekeeper, SIP, and FileVault—for a smaller unattended attack surface than many commodity PCs.
If you want CI-driven automation without renting noisy shared runners for sensitive hooks, Mac mini M4 is a practical anchor: enough performance for concurrent verifications, predictable thermals, and a total cost of ownership that looks better the longer the machine stays online.
If you are ready to place that gateway on hardware you control, start from the SSHMac home page below and pick a plan that matches your expected webhook volume.