Webhook：アーキテクチャ変更のリアルタイム通知
先週、あるチームからこんな話を聞きました。Archylでコアシステムをリネームしたそうです——C4モデル全体で「UserService」を「AccountService」に変更し、リレーションシップを更新し、ADRを書き直しました。丁寧で徹底的な作業です。問題は？そのシステムに依存していたプラットフォームチームが気づいたのは4日後、デプロイパイプラインが存在しない名前を参照してエラーになったときでした。
誰も伝えていませんでした。怠慢だったわけではありません——単にそのための仕組みがなかっただけです。アーキテクチャドキュメントは通常、プルモデルです。図を見に行く。ADRを読みに行く。見に行かなければ、知らないままです。
これはCI/CD通知が標準になる前のソフトウェア開発と同じパターンです。コード変更はかつて、mainをpullしたときに初めて気づくものでした。今日では、すべてのマージ、すべてのビルド失敗、すべてのデプロイがどこかに通知を発火します。アーキテクチャの変更も同じ扱いを受けるべきです。
アーキテクチャのプッシュ通知
Archylがwebhookをサポートするようになりました。C4モデルで何かが変わったとき——システムが作成された、コンテナが削除された、リレーションシップが更新された、リリースがデプロイされた——Archylは設定したエンドポイントにHTTP POSTを送信し、何が起きたかを正確に記述するJSONペイロードを届けます。
アイデアはシンプルです：あなたのアーキテクチャは生きたシステムです。人もツールも、デプロイイベントやプルリクエストの通知を購読するのと同じように、アーキテクチャの変更を購読できるべきです。「何か変わった？」と聞く代わりに、答えが向こうからやってきます。
44種類のイベントタイプ
モデルの半分しかカバーしない通知システムを出荷するつもりはありませんでした。WebhookはArchylが追跡するすべてのものに対して発火します：
C4要素 — システム、コンテナ、コンポーネント、コード要素の作成、更新、削除。アーキテクチャモデルの中核です。
リレーションシップ — 要素間の接続が作成、変更、または削除されたとき。これは多くの場合、最も重要なシグナルです——2つのシステム間の新しい依存関係は、複数のチームが知る必要がある種類の変更です。
ADRとドキュメント — Architecture Decision Recordやプロジェクトドキュメントの作成、更新、削除。チームがRESTからgRPCへの移行理由を説明する新しいADRを書いたとき、影響を受ける人々は3スプリント後ではなく、すぐに知るべきです。
フロー — ユーザーフローとシステムフローの変更。新規フロー、ステップの更新、フローの削除。
オーバーレイ — 図上のビジュアルグルーピングの変更。
リリース — 環境全体のデプロイイベント。リリース管理と組み合わせることで、プッシュベースの完全なデプロイ通知パイプラインが得られます。
リクエスト — アーキテクチャ変更リクエストのオープン、レビュー、マージ。
APIコントラクトとイベントチャンネル — アーキテクチャにリンクされたスペック変更と非同期メッセージングの更新。
ディスカバリーとインサイト — AI駆動のディスカバリー完了と新しいアーキテクチャインサイト。
合計44種類のイベントタイプです。必要なものだけを選べます——すべてを購読することも、ワークフローに関係する5つのイベントだけを選ぶことも可能です。
仕組み
Webhookのセットアップは約30秒で完了します。
名前を付けます（わかりやすいもの——「Slack通知」「監査ログ同期」「CIトリガー」など）。URLを設定します——POSTリクエストを受信できる任意のHTTPエンドポイントです。オプションで署名検証用のシークレットを設定します。そして、トリガーするイベントを選択します。
Webhookを特定のプロジェクトにスコープすることもできます。すべてのプロジェクトのすべての変更で発火する組織全体のWebhookは、監査ログに便利です。決済システムのリリースイベントだけで発火するプロジェクトスコープのWebhookは、そのシステムを担当するチームに便利です。
マッチするイベントが発生すると、ArchylはあなたのURLにHTTP POSTを送信し、以下を含むJSONペイロードを届けます：
- イベントタイプ — 44種類のうち、どのイベントがこの配信をトリガーしたか
- エンティティ — 変更された要素の完全な詳細
- アクター — 誰が変更を行ったか（ユーザーID、名前、メール）
- プロジェクト — どのプロジェクトで発生したか
- タイムスタンプ — いつ変更が発生したか
- 組織 — どの組織に属するか
ペイロードには変更に対応するために必要なすべてが含まれています——表示する、ログに記録する、パイプラインをトリガーする、別のシステムに同期する、どんな用途にも対応できます。
セキュリティ：HMAC-SHA256署名
すべてのWebhookリクエストには、sha256=<hex digest>形式のX-Archyl-Signatureヘッダーが付きます。これはシークレットを使用してリクエストボディの生バイトから計算されたHMAC-SHA256ハッシュです。また、X-Archyl-Event（イベントタイプ）とUser-Agent: Archyl-Webhook/1.0ヘッダーも含まれるため、送信元を識別できます。
受信側では、sha256=プレフィックスを除去し、自分が持つシークレットのコピーでリクエストボディの生バイトに対してHMAC-SHA256ハッシュを再計算し、定数時間比較（constant-time comparison）で照合します。一致すれば、リクエストは正当です。一致しなければ、誰かが偽のイベントを送信しています。
これはGitHub、Stripe、そしてほとんどのWebhookプロバイダーが使用しているのと同じ署名スキームです。シンプルで、広く理解されており、どの言語でも簡単に実装できます。OAuthフロー不要、トークンローテーション不要、証明書管理不要。共有シークレットとハッシュだけです。Go、Node.js、Pythonでの完全な検証例については、Webhookドキュメントをご覧ください。
シークレットを設定しない場合、署名ヘッダーは省略されます。VPN内の内部エンドポイントなら問題ありません。インターネットに公開されたものには推奨しません。
これで何が作れるか
最もわかりやすいユースケースはチャット通知です。Slack、Microsoft Teams、Discordはすべてインカミングwebhookをサポートしています——それらのURLをArchylに貼り付け、関心のあるイベントを選択すれば、アーキテクチャの変更がチャンネルに表示され始めます。新しいシステムが追加された。ADRが承認された。本番にリリースがデプロイされた。チームはArchylを開かずにそれを確認できます。
しかし通知は始まりに過ぎません。
外部システムへの同期 — アーキテクチャの変更をCMDB、社内Wiki、サービスカタログにプッシュします。Archylでコンテナがリネームされれば、サービスカタログが自動的に更新されます。
CI/CDパイプラインのトリガー — アーキテクチャ変更リクエストがマージされたとき、インフラ構成の再生成、Terraformモジュールの更新、実際のデプロイがドキュメント化されたアーキテクチャと一致しているかの検証を行うパイプラインを起動できます。
監査証跡 — すべてのイベントを外部ログシステムに転送します——Elasticsearch、Splunk、シンプルな追記専用データベース。Archylの7日間の配信履歴はデバッグに有用ですが、恒久的な外部ログはコンプライアンスに有用です。
カスタムダッシュボード — アーキテクチャイベントにリアルタイムで反応する社内ダッシュボードを構築できます。アーキテクチャがどのくらい頻繁に変更されるか、どのチームが最もアクティブか、どのシステムが最も変動が多いかを追跡できます。
ポイントは、WebhookがArchylをイベントソースに変えるということです。あなたのアーキテクチャモデルは、他のシステムが購読し、反応し、その上に構築できるものになります。
配信トラッキング
すべてのWebhook配信はログに記録されます。任意のWebhookの完全な履歴を確認できます：どのイベントがトリガーしたか、送信されたリクエストペイロード、レスポンスステータスコード、レスポンスボディ、送信時刻とレスポンス到着時刻のタイムスタンプ。
配信は7日間保持されます。統合の問題をデバッグするには十分な長さで、エンドポイントのレスポンスボディを無期限に保存し続けない程度の短さです。
配信が失敗した場合——サーバーからの500、タイムアウト、DNS解決エラー——赤いステータスで表示されます。エラーを確認し、エンドポイントを修正して、ワンクリックでリトライできます。リトライはまったく同じペイロードを送信するため、エンドポイントは最初から成功したかのように元のイベントを処理します。
自動リトライはありません。指数バックオフも検討しましたが、実際のところ、ほとんどのWebhook失敗はトランジェント（サーバーが再起動中だった）か構造的（URLが間違っている）のどちらかです。トランジェントな失敗には、手動リトライボタンの方がバックオフを待つより速いです。構造的な失敗には、自動リトライはノイズを生むだけです。
始め方
- 組織設定 > Webhooks に移動します
- Webhookを作成 をクリックします
- 名前を入力し、エンドポイントURLを貼り付け、シークレットを設定します
- 購読するイベントを選択します
- オプションで特定のプロジェクトにフィルタリングします
- テスト送信 をクリックして、エンドポイントがペイロードを受信することを確認します
- 保存すれば、稼働開始です
テスト配信はサンプルペイロードを含むpingイベントを送信します。エンドポイントが到達可能であること、シークレットが正しく設定されていること、ハンドラーがJSONを期待通りに処理することを確認できます。実際のイベントを購読する前にこれを行ってください。
イベントストリームとしてのアーキテクチャ
私たちは、アーキテクチャドキュメントが静的な成果物ではなく、開発ワークフローの生きた接続された一部であるバージョンに向けて構築を進めてきました。Marketplace統合は外部データをアーキテクチャに取り込みます。Webhookはアーキテクチャデータをツールに送り出します。
この組み合わせは強力です。アーキテクチャワークスペースは、単に図を見に行く場所ではありません。モニタリングツールから運用データを受信し、コミュニケーションツールや自動化ツールに変更イベントを発信するハブです。データは双方向に流れます。
誰も見ないアーキテクチャドキュメントは役に立ちません。重要なときに通知してくれるアーキテクチャドキュメント——それこそがインフラストラクチャです。
他の機能がどのようにアーキテクチャとワークフローを接続するか見てみませんか？図にライブデータを表示するMarketplace統合や、C4モデル全体でデプロイを追跡するリリース管理をご覧ください。