Webhook 通知

Webhook を使用すると、Archyl ワークスペースで何かが変更されるたびに、リアルタイムの HTTP POST 通知を受信できます。Webhook を作成し、URL を指定し、関心のあるイベントを選択すれば、それらのイベントが発生するたびに Archyl がエンドポイントに通知します。

概要

イベントが発生すると（システムの作成、リリースのデプロイ、ADR の更新など）、Archyl はそのイベントをサブスクライブしているすべての Webhook に HTTP POST リクエストを送信します。エンドポイントは、何が起こったか、誰が行ったか、どのプロジェクトに属するかを記述した JSON ペイロードを受信します。

一般的なユースケース：

• Slack や Teams への通知 — アーキテクチャの変更時
• CI/CD トリガー — 新しいリリースが作成された時
• 監査ログ — 外部システムへの記録
• カスタムダッシュボード — アーキテクチャイベントに反応
• 自動化パイプライン — ディスカバリー完了時に実行

サポートされるイベント

アーキテクチャ要素

プロジェクト管理

ドキュメント

コラボレーション & 分析

Webhook の作成

1. 組織設定 に移動し、Webhooks タブを選択します
2. 新規 Webhook をクリックします
3. 設定を入力します：

4. 作成 をクリックします

Webhook はすぐにイベントの受信を開始します。

ペイロード形式

すべての Webhook 配信は、以下の構造の JSON ペイロードを送信します：

{
  "event": "system.created",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "entityType": "system",
    "entityName": "Payment Service",
    "action": "created",
    "userName": "vincent",
    "projectId": "a1b2c3d4-...",
    "projectName": "My Project"
  }
}

Content-Type ヘッダーは常に application/json です。

セキュリティ

リクエストヘッダー

すべての Webhook 配信には、以下のヘッダーが含まれます：

HMAC-SHA256 署名検証

Webhook 作成時にシークレットトークンを設定すると、Archyl は HMAC-SHA256 を使用してすべてのペイロードに署名します。署名は X-Archyl-Signature ヘッダーで以下の形式で送信されます：

sha256=<hex-encoded HMAC-SHA256 digest>

配信を検証するには：

1. リクエストボディの生データを読み取ります（JSON パース前の正確なバイト列）
2. X-Archyl-Signature ヘッダーを読み取り、sha256= プレフィックスを除去して16進数の署名を取得します
3. シークレットトークンをキーとして、生ボディの HMAC-SHA256 ハッシュを計算します
4. 結果を16進数エンコードし、ステップ 2 の署名と定数時間比較で比較します
5. 一致しない場合はリクエストを拒否します

Go の例：

func verifyArchylWebhook(r *http.Request, secret string) ([]byte, error) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        return nil, err
    }

    header := r.Header.Get("X-Archyl-Signature")
    if !strings.HasPrefix(header, "sha256=") {
        return nil, fmt.Errorf("missing or invalid signature header")
    }
    signature := strings.TrimPrefix(header, "sha256=")

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(signature)) {
        return nil, fmt.Errorf("signature mismatch")
    }
    return body, nil
}

Node.js の例：

const crypto = require("crypto");

function verifyArchylWebhook(req, secret) {
  const header = req.headers["x-archyl-signature"] || "";
  if (!header.startsWith("sha256=")) {
    throw new Error("Missing or invalid signature header");
  }
  const signature = header.slice("sha256=".length);

  const body = req.rawBody; // use raw body, not parsed JSON
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    throw new Error("Signature mismatch");
  }
  return JSON.parse(body);
}

Python の例：

import hmac
import hashlib

def verify_archyl_webhook(body: bytes, header: str, secret: str) -> dict:
    if not header.startswith("sha256="):
        raise ValueError("Missing or invalid signature header")
    signature = header.removeprefix("sha256=")

    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Signature mismatch")
    return json.loads(body)

タイミング攻撃を防ぐため、常に定数時間比較（hmac.Equal、crypto.timingSafeEqual、hmac.compare_digest）を使用してください。また、必ず生のリクエストボディに対して検証を行ってください。JSON をパースして再シリアライズすると、バイト表現が変わり署名が一致しなくなる可能性があります。

配信履歴

すべての Webhook は最近の配信ログを保持しています。確認するには：

1. 組織設定 > Webhooks に移動します
2. Webhook 名をクリックします
3. 配信 タブを開きます

各配信エントリには以下が表示されます：

配信は 7 日間 保持されます。その後、自動的に削除されます。

緑色のバッジは配信成功（2xx レスポンス）を示します。赤色は失敗（非 2xx またはタイムアウト）を示します。

テスト

本番環境で Webhook に依存する前に、動作を確認してください：

1. Webhook の詳細ページを開きます
2. テスト送信 をクリックします
3. Archyl が event: "webhook.test" のテストペイロードをエンドポイントに送信します
4. 配信タブで受信を確認し、レスポンスを検査します

テスト配信は実際のイベントと同じ署名メカニズムを使用するため、署名検証ロジックも同時に検証できます。

リトライポリシー

配信が失敗した場合（非 2xx レスポンスまたはネットワークタイムアウト）、Archyl は自動的にリトライします：

3 回のリトライが失敗した後、配信は失敗としてマークされます。配信タブから リトライ をクリックして、失敗した配信を手動で再トリガーできます。

Webhook が 24 時間連続して失敗し続けると、Archyl はそれを無効化し、組織管理者に通知を送信します。問題が解決したら、Webhook 設定から再度有効化してください。

プロジェクトによるフィルタリング

デフォルトでは、Webhook は組織内のすべてのプロジェクトからイベントを受信します。範囲を絞り込むには：

1. Webhook を編集します
2. プロジェクト で 1 つ以上のプロジェクトを選択します
3. 保存します

選択したプロジェクトから発生したイベントのみが配信をトリガーします。異なるチームが異なるプロジェクトを管理しており、自分の作業に関する通知のみが必要な場合に便利です。

プロジェクトフィルターは、Webhook を再作成せずにいつでも更新できます。

ベストプラクティス

迅速にレスポンスを返す

エンドポイントは 10 秒以内 に 2xx レスポンスを返す必要があります。重い処理が必要な場合は、Webhook を即座に受け入れ、バックグラウンドジョブで非同期的に処理してください。

署名を検証する

常にシークレットトークンを設定し、X-Archyl-Signature ヘッダーを検証してください。これにより、ペイロードが確実に Archyl から送信されたものであり、改ざんされていないことを確認できます。

HTTPS を使用する

常に HTTPS エンドポイントを使用してください。Archyl は平文の HTTP URL に Webhook を配信しません。

プロジェクトでフィルタリングする

組織に多くのプロジェクトがある場合は、関心のあるプロジェクトに Webhook のスコープを絞ってください。ノイズを削減し、エンドポイント側の不要な処理を回避できます。

重複を処理する

まれなケース（ネットワークリトライ、インフラのフェイルオーバーなど）では、エンドポイントが同じイベントを複数回受信する場合があります。timestamp と event フィールドを使用して重複を検出・除去してください。

配信の健全性を監視する

配信タブを定期的に確認してください。失敗のパターンは、エンドポイントの問題、ファイアウォールルール、または資格情報の期限切れを示している可能性があります。

次のステップ

• マーケットプレイス連携 — 外部サービスを接続し、ダッシュボードにライブデータを表示
• リリース管理 — アーキテクチャ全体のデプロイメントを追跡
• アーキテクチャインサイト — アーキテクチャの問題を自動的に検出