osFoundry / Platform
受信ウェブフック
アプリまたはワークスペース単位でイベント受信用URLを提供。署名検証を標準装備。
概要
インバウンドWebhookは、osFoundryに外部の世界からの受け口を用意する仕組みです。特定のアプリ、インスタンス、チャネルに紐づいたトークンを発行すると、osFoundryは /api/v1/webhooks/inbound/{id} 配下の専用URLを返します。Stripe、GitHub、Zapier、CIパイプライン、自前のバックエンドといった外部システムがそのURLにJSONをPOSTすると、イベントは指定したリアルタイムチャネルに届き、そこでチャットやエージェント、アプリがそれを処理できます。ポーリングは不要で、別途連携用のサーバーを立てる必要もありません。このエンドポイント自体が連携先になります。\n\n署名検証は後付けではなく最初から組み込まれています。各トークンはHMAC-SHA256の署名シークレットを持ち、発行時に一度だけ表示されます。送信側はペイロードに対する署名を計算し、X-OsFoundry-Signatureヘッダーで渡します。osFoundryはリクエストごとにこれを検証し、署名がないものや途中で改ざんされたものは拒否します。送信側のキーを入れ替えたいときは、シークレットを更新すると7日間の猶予期間が開き、その間は以前のシークレットも有効なままです。そのため、更新の途中で処理中のイベントを取りこぼすことはありません。トークンの失効は即座に反映され、エンドポイントはすぐに401を返し始めます。これはシークレットが漏れたときや連携を廃止するときの最短の対処になります。\n\nこの仕組みはosFoundryのBYOK対応デスクトップワークスペースの中で動くため、届いたイベントは普段使っているエージェント、アプリ、ナレッジをそのまま動かせます。席数課金の連携コストはなく、第三者の仲介サービスを経由してデータが迂回することもありません。各トークンは最終利用時刻と直近24時間のリクエスト数を記録するので、どの送信側が稼働中かを把握できます。さらにプラットフォームは直近100件のインバウンドリクエストを保持しており、これを再送できます。Webhookのデバッグは当て推量ではなく、実際のペイロードを流し直す作業になります。
主な機能
- アプリ、インスタンス、チャネルごとに専用の受信URLを発行できます。外部システムは /api/v1/webhooks/inbound/{id} 配下のこのエンドポイントに、JSONイベントを直接POSTします
- すべてのリクエストは X-OsFoundry-Signature ヘッダーのHMAC-SHA256署名で検証されるため、署名のないペイロードや改ざんされたペイロードはチャネルに届く前に拒否されます
- 署名シークレットの更新には7日間の猶予期間があり、その間は以前のシークレットも有効なままです。イベントを取りこぼさずに送信側のキーを入れ替えられます
- トークンは即座に失効させられます。失効した瞬間からエンドポイントは401を返し、漏れた送信元や廃止した送信元を遮断します
- トークンごとに最終利用時刻と直近24時間のリクエスト数を確認でき、配信の調査が必要なときはトリガー設定から直近100件のインバウンドリクエストを再送できます
活用例
- Stripeを組み込む開発者：課金チャネルに紐づくトークンを発行し、StripeのWebhookをそのURLに向けます。HMAC署名が一致しないPOSTは、エージェントに届く前にosFoundryが拒否します
- シークレットが漏れた運用担当者：該当トークンを失効させて即座に401を返し、新しいトークンを発行します。ワークスペースに接続された他の連携は止めずに済みます
- CIパイプラインをつなぐ自動化担当者：ビルド状態のイベントをチャネルにPOSTし、そこでエージェントが失敗を仕分けます。直近100件のリクエストの再送を使って、ペイロードの形を調べられます
よくある質問
osFoundryはインバウンドWebhookが正当なものかをどう検証しますか
各インバウンドトークンはHMAC-SHA256の署名シークレットを持ちます。送信側はリクエストボディに対する署名を計算し、X-OsFoundry-Signatureヘッダーで送ります。osFoundryはリクエストごとにこれを再計算して照合します。署名が欠けているか無効なリクエストは拒否されるため、シークレットを持つシステムだけがチャネルに公開できます。シークレットは発行時に一度だけ表示され、後から再表示されないので、その時点で保存してください
トークンを更新または失効させると、処理中のイベントはどうなりますか
更新では7日間の猶予期間が開き、新旧どちらのシークレットも有効なままです。そのため切り替えの間にイベントを失うことなく、すべての送信側を更新できます。失効はこれとは逆の設計で、エンドポイントは即座に401を返して送信側をその場で遮断します。シークレットが漏れたときや連携を廃止するときに、まさに求める挙動です
Webhook URLはすべてで共通ですか、それとも範囲を絞れますか
各トークンは特定のアプリ、インスタンス、チャネルに範囲が絞られ、/api/v1/webhooks/inbound/{id} 配下に独自のURLを発行します。つまり、ある送信側が許可されていないチャネルに公開することはできず、他に影響を与えずに単一の連携だけを失効または更新できます。各トークンは最終利用時刻と直近24時間のリクエスト数も報告するので、どのエンドポイントが実際にトラフィックを受けているかを判別できます