Webhook

Webhook endpoint を使うと、外部システムからエージェントのイベントストリームにイベントを送信できます。各エージェントは複数の endpoint を持ち、異なる連携先に対応できます。

Endpoint の作成

1. エージェント設定 → Webhooks を開く
2. 名前を入力（例: youtube-live, discord）
3. 認証モードを選択
4. Create webhook をクリック

新しい webhook はテストモードで作成されます — 受信したペイロードはプレビュー用に保存されますが、イベントは作成されません。本番稼働前にデータ形式を確認できます。

生成される endpoint URL:

POST /api/ingest/webhook/<webhookId>

テストモード

webhook がテストモードの場合:

1. 外部アプリケーションから endpoint URL に実際のペイロードを送信
2. webhook カードの マッピング設定 ダイアログを開く
3. 受信したペイロードが ソースペイロード ドロップダウンに表示される（最新 10 件）
4. ビジュアルマッピングエディターでフィールドをイベントプロパティにマッピング
5. ライブプレビューでマッピング結果を確認
6. 正式上線 をクリックして webhook を有効化 — 以降のペイロードがイベントとして作成される

テストモードは、イベントストリームを汚さずにマッピング設定を反復できる安全な環境を提供します。

ビジュアルマッピング

マッピングダイアログには 2 つのモードがあります:

ビジュアルモード（推奨）

ビジュアルエディターは分割ビューを表示します:

• 左パネル — ソースペイロード: 受信ペイロードの JSON ツリー。ターゲットフィールドにフォーカスした状態でフィールドをクリックすると、マッピング式が自動生成されます。
• 右パネル — ターゲットフィールド: マッピングする 5 つのイベントフィールド:

フィールド	キー	必須	デフォルトテンプレート
Platform	platform	いいえ	{{ payload.platform || 'webhook' }}
Element	element	いいえ	{{ payload.username || 'external' }}
Event Type	event_type	いいえ	{{ payload.event_type || 'message' }}
Title	title	はい	{{ payload.message }}
Payload	payload	いいえ	{{ payload }}

ターゲットフィールドの下に、選択中のテストペイロードを使ったライブプレビューが表示されます。

エージェントが見る内容

5 つのマッピングフィールドは、エージェントのイベントストリームコンテキストで 1 行に組み立てられます：

- [02-21 14:35] [evt_abc123] {platform}/{element} ({event_type}): {title}

例えば、platform=youtube、element=alice、event_type=message、title=hello from chat の場合：

- [02-21 14:35] [evt_abc123] youtube/alice (message): hello from chat

payload フィールドはデータベースに保存されます。ペイロードに content フィールドが含まれる場合、title の代わりにその値が表示されます。エージェントはイベント ID（例: evt_abc123）を参照して返信やアクションを実行できます。

クリックでマッピング:

1. ターゲットフィールドをクリックしてフォーカス
2. 左の JSON ツリーでノードをクリック
3. {{ payload.path.to.field }} 式が自動挿入される
4. ライブプレビューが即座に更新

Raw モード

Raw エディタータブに切り替えて JSON を直接編集できます。マッピングは {{ payload.xxx }} テンプレート構文を使った JSON オブジェクトで記述します:

{
  "platform": "{{ payload.platform || 'webhook' }}",
  "element": "{{ payload.username || 'external' }}",
  "event_type": "{{ payload.event_type || 'message' }}",
  "title": "{{ payload.message }}",
  "payload": "{{ payload }}"
}

タブ切り替え時に双方向で同期されます。

テンプレート構文

• payload は受信 JSON ペイロードを指します
• payload.path.to.field でネストされたフィールドにアクセス（オブジェクト・配列対応、例: payload.items.0.name）
• || チェーンでフォールバック値を指定
• 'literal' はリテラル値
• {{ payload }} はペイロード全体を渡します

マッピングは空でない title フィールドを生成する必要があります。生成されない場合、422 エラーで拒否されます。

認証モード

モード	セキュリティ	ユースケース
open	なし	テスト、低リスクな内部ソース
api_key	ヘッダー/クエリ/ボディの key	key を送信できるが署名できない連携先
secret	key ベースの検証	本番推奨

api_key と secret モードでは、key は以下の順序で検出されます:

1. Authorization: Bearer <key> ヘッダー
2. X-Webhook-Key、X-API-Key、X-Webhook-Secret ヘッダー
3. クエリパラメータ: key、api_key、secret、token
4. JSON ボディフィールド: key、api_key、secret、token

カスタムヘッダーを設定できないソース（Social Stream Ninja など）でも、JSON ボディやクエリ文字列で key を渡せます。

注意

open モードは認証なしです — endpoint URL を知っている人なら誰でもイベントを送信できます。テスト目的でのみ使用してください。

認証フィールドの自動除去

テストモードでは、保存されるペイロードから認証関連フィールドが自動的に除去され、UI で認証情報が漏洩するのを防ぎます。デフォルトで以下のフィールドが除去されます:

key、api_key、secret、token、password、authorization、access_token、refresh_token、bearer

webhook 設定で追加の除外フィールドを設定できます。ユーザー設定の除外はテストモードとアクティブモードの両方で適用されます。

Endpoint ライフサイクル

ステータスフロー

webhook は 3 つのステータスのいずれかです:

ステータス	バッジ	動作
テスト	アンバー	ペイロードはプレビュー用に保存、イベントは作成されない
アクティブ	グリーン	ペイロードはマッピングされ events テーブルに書き込まれる
無効	グレー	endpoint はすべてのリクエストを 404 で拒否

利用可能な遷移:

• テスト → 正式上線（アクティブ）または無効化
• アクティブ → 一時停止（無効）またはテストモード（テスト）
• 無効 → 有効化（アクティブ）

ローテーション

ローテーションは新しい endpoint ID と key を生成し、古いものを無効にします。key が漏洩した可能性がある場合に使用:

1. endpoint カードの Rotate をクリック
2. 新しい endpoint ID と key が生成される
3. 古い endpoint は即座に無効化
4. 送信システムを新しい URL/key で更新

削除

削除された endpoint は即座に 404 を返し、イベントを受信できなくなります。

レート制限

各 endpoint にはレート制限があります（デフォルト: 120 リクエスト/分）。超過すると 429 Rate limit exceeded が返されます。

Social Stream Ninja の連携

Social Stream Ninja は 100 以上のプラットフォーム（YouTube、Twitch、TikTok など）のライブイベントを集約し、webhook に転送できます。

カスタムヘッダーなしでの設定

Social Stream Ninja はカスタム HTTP ヘッダーをサポートしない場合があります。JSON ボディに key を含む api_key モードを使用:

1. api_key 認証モードで endpoint を作成
2. 生成された key をコピー
3. Social Stream Ninja で webhook URL を設定:

   https://your-domain/api/ingest/webhook/<webhookId>

4. JSON ペイロードに key フィールドとして key を含める

ペイロード例

{
  "platform": "youtube",
  "username": "alice",
  "message": "hello from chat",
  "event_type": "message",
  "key": "your-api-key-here"
}

エラーコード

コード	ステータス	説明
WEBHOOK_NOT_FOUND	404	endpoint が存在しないか、無効/削除済み
WEBHOOK_UNAUTHORIZED	401	key が未提供または無効
WEBHOOK_MAPPING_INVALID	422	マッピング結果が無効（例: title がない）
WEBHOOK_RATE_LIMITED	429	レート制限超過
WEBHOOK_INGEST_FAILED	500	予期しないサーバーエラー

関連

• イベントストリームの概念