2026 OpenClaw MeshMac in der Praxis: Linear Webhook — minimale Schritte für geteilten Build-Status-Broadcast und Zusammenfassung zurück ins Issue

Drei typische Bruchstellen

1. Signatur nach dem Parsen: JSON-Parser vor HMAC — jede Neuformatierung bricht Linear-Signature.
2. Secret-Splitting auf Buildern: Jeder mesh_node_id besitzt Webhook-URL und Secret — Rotation und Compliance werden untragbar.
3. Retry-Stürme: Linear wiederholt Zustellungen; ohne Idempotenz starten parallele Builds und doppelte Chat-Nachrichten.

Gateway-Installation und Health-Check

1. Schritt 1 — Topologie festlegen: Nur der Gateway-Host terminiert TLS für POST /hooks/linear. MeshMac-Builder senden keine direkten Antworten an Linear. Referenz: Load-Balance und Failover.
2. Schritt 2 — OpenClaw installieren und Root setzen: Variable OPENCLAW_CONFIG_ROOT auf ein nur für den Dienstuser beschreibbares Verzeichnis zeigen; Onboarding abschließen wie in Multi-Node-Deploy beschrieben.
3. Schritt 3 — Health-Checks: Liveness prüft Prozess und Port; Readiness prüft Schreibzugriff auf Queue-Backend und Erreichbarkeit interner DNS. Dokumentieren Sie dieselben Variablen wie in CI, um Drift zu vermeiden.
4. Schritt 4 — Geheimnis ablegen: Linear Signing Secret nach /etc/openclaw/secrets.d/linear/webhook_hmac, Modus 0440, Gruppe openclaw-hooks — nie ins Repository.

Zitierfähig: Health-Endpoints sollten unter fünf Sekunden antworten und keine Benutzer-Secrets in JSON zurückgeben; so bleibt der Webhook-Pfad von Diagnose-URLs getrennt.

Linear-Signaturverifikation

1. Schritt 5 — Rohbytes puffern: Middleware-Kette so ordnen, dass der Handler zuerst den unveränderten Body als Bytefolge erhält — kein pretty-print, kein zusätzliches utf-8-Reencode vor der Prüfung.
2. Schritt 6 — HMAC berechnen: Secret aus Schritt 4 lesen; HMAC-SHA256 gemäß Linear-Dokumentation über genau diese Bytes; Zeitstempel-Header optional gegen Toleranzfenster prüfen, um Replay zu begrenzen.
3. Schritt 7 — Früh ablehnen: Bei Mismatch HTTP 401 ohne Payload-Details loggen — nur Korrelation-ID; erst bei Erfolg JSON parsen und Geschäftslogik ausführen.

Zitierfähig: In strukturierten Logs nur Issue-IDs und Delivery-Ids, niemals das komplette Secret oder Roh-JSON mit personenbezogenen Feldern.

Mit gemeinsamen Build-Skripten verketten

1. Schritt 8 — Ereignis normalisieren: Aus dem Webhook ein internes Task-Objekt mit issue_id, Team, Actor, Transition, Branch-Hinweis und provider_run_id bilden — unabhängig davon, welcher MeshMac-Knoten später ausführt.
2. Schritt 9 — Idempotenz: Schlüssel aus Linear-Delivery-Id oder Hash aus Issue plus Transition plus Minutenfenster; in die Queue schreiben wie in Task-Queue-HowTo; HTTP 200 erst nach durable enqueue.
3. Schritt 10 — Gemeinsames Skript: Worker auf beliebigem Knoten ruft ein Shell- oder Makefile-Ziel auf — Artefakt-Pfade, Xcode-Selektor und Locks sind im Skript zentral; mesh_node_id wird beim Start in die Umgebung geschrieben und in jede Statuszeile aufgenommen.

Zitierfähig: Halten Sie die Webhook-Handler-Latenz unter zweihundert Millisekunden für Ack-only; schwere Arbeit gehört in die Queue — Linear wartet nicht auf Ihren vollständigen Xcode-Build.

Fehler, Retries und Benachrichtigungen

1. Schritt 11 — Outbound-Retries: Chat-Webhooks und ähnliche Ziele: 429 und 5xx mit exponentiellem Backoff, Jitter und Cap — typisch bis fünf Versuche; 400 nicht blind wiederholen. Muster wie bei Teams-Mehrknoten-Webhook.
2. Schritt 12 — Summary zurück nach Linear: Mit scoped API-Key optional GraphQL-Kommentar: eine Zeile Status, Link zum Run, mesh_node_id — keine vollständigen Logs. Dedupe über provider_run_id plus Ziel-Kommentar-Hash im Gateway.

Zitierfähig: Trennen Sie Broadcast-Kanäle (breit, dedupliziert) von Linear-Kommentaren (schmal, auditierbar); dasselbe Ereignis darf beide Pfade auslösen, aber mit unterschiedlichen Templates.

FAQ