Webhook

概要

Webhookを使用すると、組織内で重要なイベントが発生した際にHTTP通知を受け取ることができます。APIをポーリングする代わりに、URLを登録すると、Jinba Toolboxがリアルタイムでイベントペイロードをプッシュします。 Webhookは組織ごとに（OwnerまたはAdminが）設定され、1つ以上のイベントタイプをサブスクライブできます。

イベントタイプ

イベント	説明
`tool.run.completed`	Toolの実行が正常に完了した
`tool.run.failed`	Toolの実行が失敗した
`toolset.published`	ToolSetの新しいVersionが公開された

実行イベントは、組織の実行エンドポイント（POST /v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run。SDKの run() が使用）経由の実行に対して送信されます。テスト実行、パブリックエンドポイント経由の実行、MCP呼び出しはWebhookをトリガーしません。

Webhookの設定

Webhookエンドポイントを作成する

サーバー上にPOSTリクエストを受信できるHTTPエンドポイントを設定します。エンドポイントは受信確認として 2xx ステータスコードを返す必要があります。

Webhookを登録する

APIまたはWebコンソール（組織サイドバーのWebhooks、Create Webhook）を使用して、エンドポイントURLを登録し、サブスクライブするイベントを選択します。登録とテストにはOwnerまたはAdminのセッショントークンが必要で、APIキー（Memberレベル）では 403 になります。

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/webhooks \
  -H "Authorization: Bearer <JinbaAuth session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/jinba",
    "events": ["tool.run.completed", "tool.run.failed"]
  }'

署名シークレットを保存する

Webhookを作成すると、署名シークレットが生成され、作成レスポンスで一度だけ返されます（コンソールではWebhook Createdダイアログに表示されます）。安全に保存してください。受信ペイロードの検証に使用します。以降の読み取りでは secretPreview のみが返されます。

テストイベントを送信する

テストイベントを送信して、エンドポイントが正しく動作することを確認します（コンソールにはWebhookごとに再生ボタンがあります）。テストペイロードは tool.run.completed イベントで、data: { "test": true, "message": "This is a test webhook delivery" } を含みます：

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/webhooks/{webhookId}/test \
  -H "Authorization: Bearer <JinbaAuth session token>"

Webhook設定

各Webhookには以下のプロパティがあります：

interface Webhook {
  id: string;
  organizationId: string;
  url: string;           // 送信先URL
  events: string[];      // サブスクライブしたイベントタイプ
  secret: string;        // HMAC署名シークレット（作成時のみ返される）
  enabled: boolean;      // Webhookが有効かどうか
  createdAt: Date;
  updatedAt: Date;
}

ペイロード形式

すべてのWebhook配信は、Content-Type: application/json、イベント名を含む X-Webhook-Event ヘッダー、X-Webhook-Signature ヘッダー（後述）を伴うHTTP POST で、以下の構造のJSONペイロードを送信します：

{
  "event": "tool.run.completed",
  "timestamp": "2026-02-01T12:00:00.000Z",
  "data": {
    "runId": "run_abc123",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "success",
    "durationMs": 1234
  }
}

イベント固有のペイロード

tool.run.completed

{
  "event": "tool.run.completed",
  "timestamp": "2026-02-01T12:00:00.000Z",
  "data": {
    "runId": "run_abc123",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "success",
    "durationMs": 1234
  }
}

tool.run.failed

{
  "event": "tool.run.failed",
  "timestamp": "2026-02-01T12:05:00.000Z",
  "data": {
    "runId": "run_def456",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "failed",
    "error": "channel_not_found",
    "durationMs": 567
  }
}

error はエラーメッセージの文字列です。 toolset.published

{
  "event": "toolset.published",
  "timestamp": "2026-02-01T10:00:00.000Z",
  "data": {
    "toolSetSlug": "slack-tools",
    "version": "1.3.0",
    "toolCount": 4,
    "releaseNotes": "Added thread reply support"
  }
}

署名の検証

すべてのWebhookリクエストには、Webhook署名シークレットを使用してリクエストボディから計算されたHMAC-SHA256署名を含む X-Webhook-Signature ヘッダーが付与されます。

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

ペイロードが改ざんされていないことを確認するために、サーバー側で署名を検証してください：

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// リクエストハンドラー内
const isValid = verifyWebhookSignature(
  requestBody,
  request.headers["x-webhook-signature"],
  process.env.WEBHOOK_SECRET!
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

Webhook管理API

メソッド	エンドポイント	説明
GET	`/v1/orgs/:orgId/webhooks`	Webhook一覧の取得
POST	`/v1/orgs/:orgId/webhooks`	Webhookの作成（`url`、`events`）。`secret` を返す
GET	`/v1/orgs/:orgId/webhooks/:webhookId`	Webhookの取得
PATCH	`/v1/orgs/:orgId/webhooks/:webhookId`	Webhookの更新（`url`、`events`、`enabled`）
DELETE	`/v1/orgs/:orgId/webhooks/:webhookId`	Webhookの削除
POST	`/v1/orgs/:orgId/webhooks/:webhookId/test`	テストイベントの送信。エンドポイントが `2xx` を返さない場合は `502` を返す

Webhookの作成、更新、削除、テストにはOwnerまたはAdminロールが必要です。APIキー（Memberレベル）では一覧の取得のみ可能です。

配信とリトライ動作

各配信は最大10秒間レスポンスを待ちます。2xx ステータスコードが成功とみなされます。エンドポイントが 2xx を返さない場合、配信は失敗として記録され、リトライ時刻（1分後、次に5分後、最大3回）が設定されますが、現時点ではそのリトライを処理するバックグラウンドジョブが存在しないため、実質的に各イベントの配信は1回のみです。失敗した配信は失われたものとして扱い、必要に応じてRunsページやAPIから照合してください。Webhook自体が自動的に無効化されることはありません。コンソールのActive / Disabledトグル、または PATCH の enabled で有効・無効を切り替えられます。

ベストプラクティス

ペイロードを処理する前に必ず署名を検証する — 改ざんを防止するためです。
200 ステータスを速やかに返す — Webhookの確認応答後に、重い処理は非同期で実行してください。
冪等な処理を実装する — リトライにより、Webhook配信が複数回届く可能性があります。runId やイベントタイムスタンプを使用して重複排除してください。
Webhookの健全性を監視する — テストボタンでエンドポイントを検証し、配信失敗を調査してください。
必要なイベントのみサブスクライブする — 統合に必要なイベントだけを選択して、ノイズを減らしてください。

Docs

概要

イベントタイプ

Webhookの設定

Webhook設定

ペイロード形式

イベント固有のペイロード

署名の検証

Webhook管理API

配信とリトライ動作

ベストプラクティス

関連ドキュメント

​概要

​イベントタイプ

​Webhookの設定

​Webhook設定

​ペイロード形式

​イベント固有のペイロード

​署名の検証

​Webhook管理API

​配信とリトライ動作

​ベストプラクティス

​関連ドキュメント

概要

イベントタイプ

Webhookの設定

Webhook設定

ペイロード形式

イベント固有のペイロード

署名の検証

Webhook管理API

配信とリトライ動作

ベストプラクティス

関連ドキュメント