Scheduled beats · Inbound webhooks · CI callbacks and idempotency
Small teams already run OpenClaw Gateway but may skip Slack-style IM yet still need scheduled checks, inbound webhooks, and CI conclusions to drive automation. This article defines three trigger classes, an auth and idempotency matrix, and a six-step Runbook you can paste into an on-call wiki. The closing section anchors common production numbers and states when hosted Mac nodes reduce operational drag.
Chat channels carry implicit context about who spoke and in which thread. Pure HTTP and cron flows lose that unless you encode contracts up front. Review these failure modes before go-live:
Duplicate delivery doubles side effects: CI platforms and webhook relays often retry on timeouts. Without idempotency keys and a dedupe window, the same job success may execute twice.
Weak authentication: Secret URLs leak through logs and proxies. Move to header secrets, HMAC, or mTLS at minimum.
Cron collides with maintenance: Patching an always-on node while cron still fires can run handlers in a half-initialized state.
Ordering myths across regions: First received is not first occurred; carry event time and a monotonic sequence.
Thin observability: Without request id, upstream job id, and idempotency fingerprints, tickets cannot map to logs.
Treat triggers like product requirements: latency sensitivity, consistency needs, and acceptable drift decide between cron, webhook, or CI callbacks.
| Trigger | Typical use | Strength | Main risk |
|---|---|---|---|
| Scheduled beat | Health sweeps, daily summaries, temp cleanup | Predictable load, simple ops | Detached from real events; pause during maintenance |
| Inbound webhook | Ticketing hooks, approvals, monitoring HTTP exporters | Near real-time alignment with business events | Duplicates, forged senders, TLS and proxy complexity |
| CI terminal callback | Post-build signing, release gates | Strong binding to artifacts | Opaque platform retries; payload version drift |
Practical pairing
Use webhooks or CI callbacks plus idempotent storage for side effects that must happen once. Reserve cron for read-only aggregation. When Gateway faces the public internet, terminate TLS and narrow listeners at the edge; follow the install and Gateway troubleshooting checklist for baseline checks.
Execute in order: validate, then widen traffic. Rename secrets to match your vault policy.
Freeze the contract: Require JSON fields event_time, source, job_id, idempotency_key, payload_version; reject unknown payloads without a version.
Authenticate at the edge: Validate Authorization bearer or HMAC at the reverse proxy with IP allowlists; Gateway only trusts internal hops.
Add idempotent storage: Use idempotency_key as primary key with TTL (often 24–72h for CI); duplicate posts return the same business response.
Gate cron during maintenance: Use a flag file or key-value gate; scripts exit early with a heartbeat log when maintenance is active.
Wire observability triplets: Generate request_id per ingress, return it in a response header, and log job_id plus hashed idempotency keys.
Chaos the retries: POST three duplicates, drop upstream for 30 seconds, recover, and confirm no double side effects and correct paging.
curl -sS -X POST "https://gateway.example.internal/hooks/ci" \
-H "Authorization: Bearer ${HOOK_SECRET}" \
-H "X-Idempotency-Key: ${CI_JOB_ID}-${CI_CONCLUSION}" \
-H "X-Request-Id: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"payload_version":1,"job_id":"'"${CI_JOB_ID}"'","conclusion":"success"}'
Threat models differ for internal-only versus public ingress. Use the matrix to align reviewers quickly.
| Pattern | Fit | Must configure |
|---|---|---|
| Shared secret + TLS | Private network or zero-trust tunnel | Rotate secrets; never echo secrets in responses |
| HMAC signatures | Public webhooks, many upstreams | Timestamp window near ±300s; constant-time compare |
| mTLS | Enterprise CI to control plane | Short-lived leaf certs with rotation and revocation |
Idempotency key shape. Prefer {source}:{stable_id}. Avoid millisecond-only keys because retries break dedupe instantly.
Never log raw secrets. Store hashed or prefixed identifiers only; logging vendors become a second blast radius.
These ranges summarize common production practice; tune to your SLA rather than treating them as vendor guarantees.
Self-hosting schedulers and laptops works until sleep, flaky home networks, and OS upgrades turn cron and webhooks into half-success states. Placing Gateway and ingress on VpsMesh always-on Mac Mini cloud nodes typically stabilizes egress IPs, maintenance windows, and hardware isolation, moving non-IM automation from hobby scripts to an on-call friendly loop.
Yes when ingress is constrained, idempotent, and observable. Stabilize Gateway first with the install and doctor checklist, then open webhooks.
Duplicates and missing sender proof. Add shared secrets or HMAC, IP limits at the edge, and identical semantics on idempotent hits. Compare node options on the pricing page when you need stable egress.
Stagger maintenance against cron peaks, keep clocks disciplined, and widen cross-region callback timeouts. Remote Mac guidance lives in the Help Center.