YouTrack Webhook Triggers の設定
Webhook Triggers は application/json の POST。共有トークンは 32 文字以上（推奨 openssl rand -hex 32）、既定ヘッダは X-YouTrack-Token（名称は変更可）。URL はHTTPS のゲートウェイ 1 本だけ登録し、まず issueUpdated など狭いイベントから始めます。
- 手順 1. 管理画面でアプリをプロジェクトに付与し、トークン・ヘッダ名・
https://<gateway>/youtrack/webhookを保存。 - 手順 2.
changedFieldsをフィルタしてからキュー投入し、平文 HTTP は使わない。
受信トークン検証（X-YouTrack-Token）
生ボディ HMAC ではなくヘッダの共有秘密です。JSON より先にヘッダを読み、秘密ファイルと定数時間比較、不一致は 401。durable エンキュー後だけ 200 を返し再送幽霊を抑止します。
- 手順 1. 期待値を
0440相当でゲートウェイのみが読めるパスに置く。 - 手順 2. 必要なら出口 IP allowlist／mTLS をエッジで足す。
多ノードルーティングと正規化
検証後は issue_id 等を揃えたタスクを共有キューへ dequeue、完了に mesh_node_id。チャット URL はゲートウェイのみ、Mac ごとに YouTrack URL は増やしません。
- 手順 1. キュー投入は冪等キーで去重（連続編集ではデバウンスや「ビルド準備」ラベルも有効）。
- 手順 2. 同時実行・タイムアウトはゲートウェイの上限に合わせ、ホスト CI とのレーン衝突をドキュメント化。
再試行・指数バックオフ・要約返却・ローテ
受信再送と出站は分離。429／一時 5xx のみ指数バックオフ＋ジッター、idempotency_key + state で重複を抑止。失敗コメントは数行、REST token は最小権限でゲートウェイのみ。ローテは秘密を先にゲートウェイ→YouTrack 更新→疎通→旧値廃棄、REST は短時間デュアル後に失効。四半期＋インシデント即時推奨。
- 手順 1.
400／401は修正まで再試行ループに入れない。 - 手順 2. チャットと REST が続けて失敗したらオンコールへページ。
FAQ
- HMAC 署名で検証しますか
- いいえ。共有トークンを設定したヘッダで届きます。定数時間一致と HTTPS が中心です。
- ノードごとに Webhook URL を分けたい
- 秘密と監査が分散するため非推奨。ゲートウェイ一本に集約してください。
まとめ・次の一手（公開ページのみ）
入口一本・キュー共有・チャット一本化・短い REST 返却・ローテの五点で通知閉ループを閉じます。購入・ヘルプ・ホーム・ブログ・OpenClaw 特集 はログイン不要です。