webhook-transforms

Webhook の変換

契約

このスキルでは、以下を保証します。

• 外部イベントが適切な引用情報付きで brain ページに変換されます
• 生のペイロードが保持されます（変換に失敗した場合はデッドレターキューに格納）
• 変換されたすべてのイベントでエンティティ抽出が実行されます
• 入力のサニタイズ：生の HTML／スクリプトが brain ページに渡されることはありません
• エラー処理：変換に失敗した場合は生のペイロードをログに記録し、一度再試行します

フェーズ

1. 変換を定義します。 イベントスキーマを brain ページ形式にマッピングします。

   • 入力：生の webhook ペイロード（JSON）
   • 出力：brain ページのコンテンツ（markdown）＋メタデータ（slug、type、引用情報）
   • サニタイズ必須：HTML タグを削除し、スクリプトのコンテンツをエスケープします

2. Webhook URL を登録します。 外部サービスに webhook エンドポイントを提供します。

3. イベント受信時：

   • ペイロードを解析します
   • 変換関数を実行します
   • gbrain put で brain ページを書き込みます
   • エンティティを抽出し、エンリッチメントを実行します
   • 言及されたエンティティにタイムラインエントリを追加します
   • 同期します：gbrain sync

4. エラー処理：

   • 変換で例外が発生した場合：生のペイロードを _dead-letter/{timestamp}.md に記録します
   • エラーの種類をエージェントに通知します
   • 一度再試行します
   • イベントを失わないようにします

変換例

SMS 受信

Input: {from: "+1555...", body: "Meeting moved to 3pm", timestamp: "..."}
Output: Timeline entry on sender's brain page + task update if action item detected

ミーティング完了

Input: {title: "Weekly sync", attendees: [...], transcript: "...", summary: "..."}
Output: Delegate to meeting-ingestion skill

ソーシャルメディアでの言及

Input: {platform: "twitter", author: "@handle", text: "...", url: "..."}
Output: Brain page in media/ + entity extraction + backlinks

出力形式

イベントを変換し、brain に書き込みました。次のように報告します：「Webhook：{source} からの {event_type} → {brain_page_path}」

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェントオペレータープロトコルに従ってください。このスキル固有の内容は以下のとおりです。

• 変換後の書き込みが write_pending（終了コード 10）を返した場合：イベントは受理されています。リクエスト ID を記録してポーリングし、新しい ID でイベントを再送信しないでください。
• source_binding_required／insufficient_scope：webhook のトークンには、そのソースへの書き込み権限がありません。brain ホストのオペレーターが追加する必要のある権限をユーザーに伝えてください。
• ペイロードの形式が不正な場合：解析エラーを示して拒否し、ログに記録してください。不完全なページを書き込まないでください。

アンチパターン

• 生の HTML／スクリプトを brain ページに渡す（XSS のリスク）
• 変換に失敗したときにイベントを黙って破棄する（デッドレターキューを使用してください）
• エンティティ抽出を行わずに webhook を処理する
• brain への書き込み前に外部入力をサニタイズしない