2026 OpenClaw MeshMac in der Praxis: Asana-Webhook — minimale Schritte für Mehrknoten-Build-Status, Broadcast und Fehler-Zusammenfassung zurück ins Ticket

Drei Unterschiede zu „noch ein weiterer Webhook“

1. Handshake blockiert die Erstellung: Der ausgehende createWebhook-Aufruf endet erst, wenn Ihr Ziel den X-Hook-Secret-Handshake korrekt beantwortet — der Dienst muss also parallel empfangen können.
2. Ereignisse sind kompakt: Der Body enthält nur events — Details holen Sie per REST nach; ohne Entlastung entstehen 429-Kaskaden.
3. Heartbeats sind Pflicht: Etwa alle acht Stunden sendet Asana Lieferungen, mitunter mit leerer Ereignisliste; ohne 200/204 wird die Subscription verworfen.

Asana ausgehender Webhook und Handshake

1. Schritt 1 — Ressource wählen: Hängen Sie den Webhook sinnvollerweise an ein Projekt oder eine Aufgabe, nicht an jeden Builder. Legen Sie filters so fest, dass nur task-Änderungen Ihrer „Ready to build“-Logik ankommen — sonst feuert jede Tastatureingabe in Langtextfeldern.
2. Schritt 2 — Ziel-URL auf dem Gateway: Nur der OpenClaw-Host mit gültigem Zertifikat exponiert POST /hooks/asana/<routing-key>. MeshMac-Knoten bleiben ohne öffentliche Webhook-URL.
3. Schritt 3 — Handshake implementieren: Asana sendet einen POST mit Header X-Hook-Secret. Antworten Sie mit HTTP 200 oder 204 und setzen Sie denselben Header-Namen und -Wert auf der Response — das bestätigt den gemeinsamen Schlüssel für spätere HMACs.
4. Schritt 4 — Secret persistieren: Speichern Sie X-Hook-Secret verschlüsselt oder als Datei 0440, verknüpft mit webhook_gid und Ressourcen-GID. Vergleichen Sie nach erfolgreicher Erstellung optional den Secret-Fingerprint mit dem Rumpf der Asana-Antwort, damit kein Downgrade zwischen Handshake und Speicher stattfand.

Betriebsnotiz: Asana erwartet Antworten typischerweise innerhalb von zehn Sekunden und wiederholt bei Fehlern mit Backoff bis zu etwa vierundzwanzig Stunden — halten Sie den Handshake- und Event-Pfad schlank und verschieben Sie Build-Arbeit in Worker.

Signaturprüfung (X-Hook-Signature)

1. Schritt 5 — Rohbytes puffern: Lesen Sie den Request-Body als Bytefolge, bevor ein Framework ihn als Objekt materialisiert — jede erneute Serialisierung bricht die Signatur.
2. Schritt 6 — HMAC berechnen: Verwenden Sie das gespeicherte X-Hook-Secret als Schlüssel und den vollständigen Rohbody als Nachricht; Algorithmus HMAC-SHA256 gemäß Asana-Dokumentation; vergleichen Sie das Ergebnis zeitkonstant mit dem Header X-Hook-Signature.
3. Schritt 7 — Früh ablehnen: Bei Mismatch HTTP 401 ohne sensitive Details im Klartext loggen — nur Korrelations-ID; bei Erfolg JSON parsen und events iterieren. Leere Arrays sind gültig und sollten mit 204 quittiert werden können.

Sicherheitsdisziplin: Trennen Sie Hook-Secret (Inbound-Authentizität) und PAT/OAuth (Outbound-Schreiben) in getrennte Geheimnisdateien mit unterschiedlichen Rotationstakten.

OpenClaw-Gateway-Routing

1. Schritt 8 — Ereignis normalisieren: Für jedes kompakte Ereignis bilden Sie ein internes Task-Objekt mit resource.gid, Aktion, Parent-Projekt und einem stabilen provider_run_id aus Webhook-GID plus Monotonie-Zähler.
2. Schritt 9 — Detailabruf entkoppeln: Worker oder ein schlanker Gateway-Consumer ruft Asana REST für den aktuellen Aufgabenstatus auf — niemals schwere Netzwerkpfade im synchronen Webhook-Thread.
3. Schritt 10 — Idempotenz und Queue: Schlüssel aus webhook_delivery-Hash oder aus task_gid plus Minutenfenster; schreiben Sie in die gemeinsame Queue wie in der Task-Queue-Anleitung beschrieben; HTTP 200/204 erst nach durable enqueue.
4. Schritt 11 — Knotenbindung: Der Scheduler setzt mesh_node_id, bevor Build-Skripte starten — sichtbar in Logs und Broadcasts, damit Incident-Teams sofort den richtigen Mac ansprechen.

Mehrknoten-Benachrichtigungs-Templates

1. Schritt 12 — Einheitliches Kurzformat: Definieren Sie ein Template mit Feldern task_url, branch oder custom_field_snapshot, conclusion (success/failure), mesh_node_id, provider_run_id und optional duration_s.
2. Schritt 13 — Broadcast deduplizieren: Chat-Webhooks (Slack, Teams, Matrix) nur einmal pro Run aus dem Gateway feuern; nutzen Sie einen kurzlebigen Cache-Schlüssel aus Run-ID und Kanal, damit parallele Knoten keine Doppelposts erzeugen.
3. Schritt 14 — Fehler-Zusammenfassung zurück nach Asana: Nur das Gateway schreibt mit minimalem Token eine eine Zeile Story oder Kommentar: Exit-Code, letzte zehn Logzeilen gekürzt, Link zum Artefakt-Store — keine vollständigen Umgebungsvariablen. Wiederholen Sie fehlgeschlagene Schreibversuche mit Backoff, respektieren Sie aber 429 vom Rest-API-Limit.

Operative Klarheit: Trennen Sie lauten Chat-Broadcast (breit, entschärft) von Asana-Rückkanal (schmal, auditierbar); dieselbe Pipeline darf beide auslösen, aber mit unterschiedlichen Redigierregeln.

FAQ: typische 401- und 429-Fälle