Asana 出站 Webhook
Webhook はインフラとして一本化し、各 Mac に公開 URL を増やしません。TLS 終端と本文上限は既存の HTTPS 方針に合わせ、バースト時もゲートウェイ CPU が枯れないよう同時配送数を見積もります。
- 手順 1. 開発者コンソールのアプリから対象リソース（プロジェクト／チーム等）に
POST先を登録。例https://gateway.example/openclaw/v1/asana/webhookのように専用パスに限定。 - 手順 2. 初回
POSTの握手で、リクエストヘッダX-Hook-Secretを応答ヘッダへそのまま返し200または204。以降の署名鍵としてファイルに保存し、ビルダーイメージには載せない。 - 手順 3. 秘密はゲートウェイのみ、権限は
0440相当でサービスユーザーに限定（MeshMac ノードの秘密と最小権限）。 - 手順 4. エッジでイベント種別を絞り、「ビルド対象」セクション遷移や合意したカスタムフィールドが付いたときだけキューへ。ノイズは署名確認後に速やかに
200。
署名検証（X-Hook-Signature）
検証してから JSON を読む。Asana は受信バイト列全体に対する HMAC-SHA256 を X-Hook-Signature（16 進）で送ります。先にパースすると本番だけ不一致、という典型事故になります。
- 手順 1. ミドルウェアより前に生ボディをバッファ化。
- 手順 2. 保存した
X-Hook-Secretで HMAC-SHA256 を計算し 16 進化、ヘッダ値と定数時間比較（ハートビートは空 JSON があり得る）。 - 手順 3. 不一致は
401。ログはdelivery_id・バイト長などマスク済みメタのみ。 - 手順 4. 検証後にエンベロープを解析し、
delivery_idまたはresource.gid + action + changed_atの短時間窓ハッシュで去重してから投入。 - 手順 5. キュー書き込みが durable になってから
200。再送でジョブが二重に積まれないよう、手順は タスクキュー再試行 と整合。
OpenClaw ゲートウェイルーティング
ルーティングは「Asana のイベント」と「ワーカー共通の正規化タスク」の契約です。写像表で (resource_type, action) を決め、task_gid とカスタムフィールドから repo／ref を抜きます。
- 手順 1.
idempotency_keyをwh_asana_{delivery_id}等で固定化（欠ける経路は決定的ハッシュ）。 - 手順 2. 共有キューへ
repo・ref・correlation_idを載せ、任意でpreferred_mesh_node_id（GPU レーン等）。静的フリートでない限りハードバインドは避ける。 - 手順 3. 「スケジュール済み」内部イベントを出し、秒単位でカードが動いてもキュー深度が見えるようにする。
- 手順 4. ハンドラ時間と同時接続は ゲートウェイのレート制限・並行 FAQ に合わせ、429 で入口が自壊しない余白を残す。
多ノード通知テンプレート
各 Mac が個別に Slack／Teams／Chat へ送ると、多ノードほどノイズと 429 が増殖します。出站テンプレはゲートウェイ一本に集約し、ワーカーは完了イベントだけを上げます。
最小 JSON：build_id、idempotency_key、task_gid＋タイトル、mesh_node_id／ホスト／ツールチェーン、status、duration_ms、exit_code、上限 log_tail。failed はゲートウェイが結果一行・疑い原因一行・ログ導線を短く組み、詳細はストレージへ。Asana には要約ストーリーのみ REST で返す。
401／429 切り分け FAQ
- Asana が叩く URL が 401
- 受信署名の世界。秘密ファイルの取り違え、ボディ改変、WAF／gzip の再符号化を疑い、ステージングと同じエッジでバイト列長を突き合わせます。
- コメント返却だけ 401
- 出站 PAT／OAuth の期限切れ・スコープ不足・ワークスペース不一致。401 を無限ループせず鍵更新。Webhook 署名と混同しない。
- Asana REST やチャットが 429
Retry-After尊重、無ければ指数バックオフ＋ジッタ、タスク単位でコメントを直列化し、build_id＋結果で去重。インシデント時の並列ノードによる送信増幅を抑える。- カラム移動が速いと二重ジョブ
- 「ビルド準備完了」カスタムフィールド必須やデバウンス、
task_gid＋セクション＋5 分バケットで冪等キーを組む。
まとめ（公開ページ）
一本の HTTPS 入口・生ボディ署名・durable キュー・同一通知 JSON・ゲートウェイからの短い Asana ストーリーが多ノード最小セットです。ナビは公開のみ：ホーム、ブログ一覧、ヘルプセンター、OpenClaw 特集。購入（プラン） は下段 CTA から。