Webhook

概要

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

イベントタイプ

イベント	説明
`tool.run.completed`	Toolの実行が正常に完了した
`tool.run.failed`	Toolの実行が失敗した
`toolset.published`	ToolSetの新しいVersionが公開された
`member.added`	組織に新しいメンバーが追加された
`member.removed`	組織からメンバーが削除された

Webhookの設定

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

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

Webhookを登録する

APIまたはWebコンソールを使用して、エンドポイントURLを登録し、サブスクライブするイベントを選択します。

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

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

Webhookを作成すると、署名シークレットが生成されます。安全に保存してください。受信ペイロードの検証に使用します。

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

テストイベントを送信して、エンドポイントが正しく動作することを確認します：

curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/webhooks/{webhookId}/test \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx"

Webhook設定

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

interface Webhook {
  id: string;
  orgId: string;
  url: string;           // 送信先URL
  events: string[];      // サブスクライブしたイベントタイプ
  secret: string;        // HMAC署名シークレット
  enabled: boolean;      // Webhookが有効かどうか
  createdAt: Date;
}

ペイロード形式

すべてのWebhook配信は、以下の構造のJSONペイロードを送信します：

{
  "event": "tool.run.completed",
  "timestamp": "2026-02-01T12:00:00Z",
  "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:00Z",
  "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:00Z",
  "data": {
    "runId": "run_def456",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "failed",
    "error": {
      "name": "SlackAPIError",
      "message": "channel_not_found"
    },
    "durationMs": 567
  }
}

toolset.published

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

member.added

{
  "event": "member.added",
  "timestamp": "2026-02-01T09:00:00Z",
  "data": {
    "userId": "user_xyz789",
    "email": "newmember@example.com",
    "role": "member"
  }
}

署名の検証

すべての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の作成
PATCH	`/v1/orgs/:orgId/webhooks/:id`	Webhookの更新
DELETE	`/v1/orgs/:orgId/webhooks/:id`	Webhookの削除
POST	`/v1/orgs/:orgId/webhooks/:id/test`	テストイベントの送信

リトライ動作

エンドポイントが 2xx ステータスコードを返さない場合、Jinba Toolboxは配信をリトライします：

試行	遅延
1回目のリトライ	1分
2回目のリトライ	5分
3回目のリトライ	30分

3回連続で失敗すると、Webhookは自動的に無効化されます。根本的な問題が解決されたら、WebコンソールまたはAPIから手動で再有効化できます。

ベストプラクティス

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

Docs

概要

イベントタイプ

Webhookの設定

Webhook設定

ペイロード形式

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

署名の検証

Webhook管理API

リトライ動作

ベストプラクティス

関連ドキュメント

​概要

​イベントタイプ

​Webhookの設定

​Webhook設定

​ペイロード形式

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

​署名の検証

​Webhook管理API

​リトライ動作

​ベストプラクティス

​関連ドキュメント

概要

イベントタイプ

Webhookの設定

Webhook設定

ペイロード形式

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

署名の検証

Webhook管理API

リトライ動作

ベストプラクティス

関連ドキュメント