100monkeys.ai

ブログ · ガイド · 2026年10月29日

署名付き Webhook から AEGIS ワークフローを起動する

他の言語: English, Español, Português, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · 日本語のガイド一覧

開示: AEGIS は 100monkeys.ai が開発しているため、このガイドは作り手による説明として読んでください。公開されている AEGIS ドキュメントの Configuring Webhooks をもとに当社の AI エージェントが下書きし、当社が確認しました。この日本語版は英語の原文ガイドの翻訳です。以下のコマンドとコードはそのページからそのまま写したもので、このガイドのためにはどれも実行していません。引用は英語のまま載せ、訳を添えています。ドキュメントが答えていない点は、最後の節に書いています。

AEGIS by 100monkeys.ai, in beta は、ほかのシステムからイベントが届いたときにワークフローを起動できます。GitHub への push、CI ジョブの完了、HTTP リクエストを送れるどんなサービスでもかまいません。送信側はあなたのノードにアカウントを持つ必要がありません。ドキュメントの言葉では "Authentication is handled by HMAC-SHA256 signature verification, not OAuth."(認証は OAuth ではなく HMAC-SHA256 署名の検証で行う)です。このガイドでは 1 つの送信元を、共有シークレットから試験済みのリクエストまで通しで設定し、途中で出会うエラーも扱います。

ステップ 1. 送信元に名前を付ける

Webhook はすべて POST /v1/webhooks/{source} に届きます。送信元は "a lowercase slug that identifies the system sending the event"(イベントを送るシステムを表す小文字のスラッグ)で、github、stripe、my-ci などです。送信システムごとに 1 つ選んでください。シークレット、ルート、重複チェックはすべてこれをキーにします。

ステップ 2. オーケストレーターに共有シークレットを設定する

シークレットはテナントと送信元の組ごとなので、どちらも送信元を github と呼ぶ 2 つのテナントは "completely independent secrets"(まったく独立したシークレット)を持ちます。組ごとにオーケストレーターの環境変数が 1 つあり、名前は次のパターンです。

# Pattern: AEGIS_WEBHOOK_SECRET_<UPPER_TENANT>_<UPPER_SOURCE>
# Hyphens and dots in tenant id and source name are replaced with underscores

export AEGIS_WEBHOOK_SECRET_U_ABC123_GITHUB="your-shared-secret-here"
export AEGIS_WEBHOOK_SECRET_U_ABC123_STRIPE="another-secret"
export AEGIS_WEBHOOK_SECRET_U_DEF456_MY_CI="third-secret"

たとえばテナント u-abc123 と送信元 my-ci なら AEGIS_WEBHOOK_SECRET_U_ABC123_MY_CI を読みます。解決した組の変数がなければ、リクエストは 401 secret_not_found で拒否されます。同じシークレットを送信側にだけ渡し、ほかの誰にも渡さないでください。

ステップ 3. 送信元をワークフローへルーティングする

直接ルートは送信元を 1 つのワークフローに対応づけるので、ルーティングは "instant and deterministic"(即時かつ決定的)です。現在のリリースでは直接ルートは "configured via orchestrator workflow routing configuration"(オーケストレーターのワークフロールーティング設定で構成する)もので、ページには "there is no aegis stimulus routes CLI command yet"(aegis stimulus routes という CLI コマンドはまだない)とあります。直接ルートがなければ、パイプラインは設定済みの RouterAgent に任せ、言語モデルでイベントを分類します。どちらもなければ、リクエストは 422 no_router_configured で失敗します。既知の送信元が 1 つなら、直接ルートを選んでください。同じイベントがいつも同じワークフローを起動します。

ステップ 4. 送信側で生のボディに署名する

送信側は共有シークレットでリクエストの生のボディの HMAC-SHA256 を計算し、sha256= を前に付けて X-Aegis-Signature で送ります。ドキュメントの Python の例です。

import hashlib
import hmac
import json
import requests

def sign_payload(body: bytes, secret: str) -> str:
    sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return f"sha256={sig}"

payload = json.dumps({"event": "push", "ref": "refs/heads/main"}).encode()
signature = sign_payload(payload, WEBHOOK_SECRET)

requests.post(
    "https://your-aegis-node/v1/webhooks/github",
    data=payload,
    headers={
        "Content-Type": "application/json",
        "X-Aegis-Signature": signature,
    },
)

ページには同じ処理の Node.js 版もあります。ページが太字にしている規則は、解析する前の生のボディのバイト列で HMAC を計算することです。"Computing over a re-serialized object will produce a different signature."(シリアライズし直したオブジェクトで計算すると別の署名になる)からです。送るバイト列そのものに署名してください。

ステップ 5. curl でエンドポイントを試す

# Generate a test signature
SECRET="your-shared-secret-here"
BODY='{"event":"push","ref":"refs/heads/main"}'
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"

# Send the test webhook
curl -X POST https://your-aegis-node/v1/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-Aegis-Signature: $SIG" \
  -d "$BODY"

成功すると 2 つの ID が返ります。

{
  "stimulus_id": "stim-uuid",
  "workflow_execution_id": "wfex-uuid"
}

2 つ目がイベントで起動したワークフローの実行です。ほかの実行と同じように追ってください。

ステップ 6. 重複配信を止める

送信側は再送します。プロバイダーの配信 ID を X-Idempotency-Key として渡してください。GitHub なら X-GitHub-Delivery、自前の送信側なら "Any stable per-event UUID"(イベントごとに変わらない任意の UUID)です。オーケストレーターは送信元とキーで 24 時間重複を除き、繰り返しには 409 を返します。

{
  "error": "idempotent_duplicate",
  "original_stimulus_id": "stim-original-uuid"
}

ステップ 7. 返ってきたエラーを読む

ページのエラー表を、出会いそうな順に並べます。

ステップ 8. 内部の呼び出し元には認証付きエンドポイントを使う

すでに Keycloak のアカウントを持つサービスは、共有シークレットを使わず、bearer トークンで POST /v1/stimuli に送れます。ボディには source、content、idempotency_key を入れます。Webhook のルートは、自分で運用していないシステムのために残してください。

ドキュメントが答えていないこと

次に読むもの

Webhook が起動するワークフローは、あなたが書く状態機械です。ガイドAEGIS ワークフローの状態と遷移を一歩ずつで 1 つ組み立てています。AEGIS は 100monkeys.ai に載っているコマンドでインストールできます。

curl -fsSL https://get.100monkeys.ai | bash

AEGIS をインストール