Webhook
Webhook を使用すると、Kanera で作業が変更されたときに外部システムが反応できるようになります。
別のシステムが API を絶えずポーリングせずに変更を知る必要がある場合は、Webhook を使用します。一般的な例は次のとおりです。
- 外部ダッシュボードを更新します。
- 変更されたカードを別のシステムに同期します。
- 導入をトリガーするか、ワークフローを確認します。
- Kanera のアクティビティを監査システムに記録します。
カードのアクティビティをチーム チャット チャネルに投稿するには、独自の Webhook は必要ありません。Kaneraは内蔵されています チャットの宛先 Slack、Discord、Telegram、Zulip では、プラットフォーム用に各メッセージをフォーマットします。完全なイベント カタログ、正確なペイロード、署名の検証が必要な場合は、Webhook を使用します。
ワークスペース管理者は、次から Webhook エンドポイントを作成できます。 ワークスペース設定 -> API、で カスタム Webhook セクション。スタンドアロンボードにも同じものがあります API タブを独自のボード設定に移動します。統合では、パブリック API または TypeScript SDK を通じてエンドポイントを登録することもできます。
各 Webhook 宛先は、すべてのイベントを受信することも、選択したイベント タイプのみを受信することもできます。休暇を取る eventTypes すべてのイベントを受信する場合は空、または以下のイベント タイプ文字列を 1 つ以上指定します。
計画と権限
- ワークスペース管理者は、そのワークスペース内のすべての汎用 Webhook エンドポイントを表示および管理できます。
- 書き込み可能な API 資格情報または対話型 OAuth エージェントは、ユーザーがワークスペース メンバーである場合、管理者権限なしでエンドポイントを登録できます。このエンドポイントのスコープは、作成中の接続に限定されます。同じ接続とワークスペース管理者のみがそれを表示または管理できます。読み取りスコープの資格情報では Webhook を管理できません。
- Webhook には必要なものがあります Pro または30日間 プロトライアル。ホストされた無料では利用できません。
- ホストされた Free では、作成フォームは次のように置き換えられます。 Webhook はあなたのプランでは利用できません.
資格情報またはエージェント接続を取り消すと、その接続スコープのエンドポイントも削除されます。管理者が作成したワークスペース エンドポイントは、管理者が削除するまで残ります。
ダウングレード時に何が起こるか
ホストされている組織が Pro またはトライアルから Free に移行すると、Kanera は何も削除せずに、有効になっているすべての Webhook エンドポイントを一時停止します。また、ワークスペース API キーが取り消され (個人キーは機能し続けます)、無料制限を超える自動化は無効になります。
| ホスト型で無料 | 行動 |
|---|---|
| 既存のエンドポイント | 自動的に一時停止され、組織が無料である間は再度有効にすることはできません。 |
| 新しいアクティビティ | エンドポイントには届きません。 |
| まだ送信を待っているもの | 失敗として記録される webhooks are unavailable on the current plan 遅く送信されるのではなく。 |
| 配信の失敗 | 手動で再試行することはできません。 |
| 構成と歴史 | 保管されています。エンドポイント、イベントの選択、シークレット、配信履歴はすべてそのまま残ります。 |
Pro にアップグレードして戻すと、ダウングレードによって一時停止されたエンドポイントが再度有効になり、取り消されたワークスペース API キーが復元されるため、再開された統合を再構築する必要はありません。
プログラムでエンドポイントを登録する
パブリック API は、ワークスペース設定で使用されるのと同じ汎用エンドポイントのライフサイクルを公開します。以下のすべてのパスは以下に対する相対パスです。
/api/v1/workspaces/{workspaceId}/webhooks
| 方法 | パス | 使用する |
|---|---|---|
GET | (ベースパス) | 呼び出し元に表示されるエンドポイントをリストします。 |
POST | (ベースパス) | エンドポイントを作成し、その署名シークレットを 1 回返します。 |
PATCH | /{endpointId} | 名前、URL、イベント フィルター、または有効な状態を変更します。 |
POST | /{endpointId}/secret | 署名シークレットをローテーションします。 |
DELETE | /{endpointId} | エンドポイントを削除します。 |
GET | /{endpointId}/deliveries | 最近の配信試行を読み取ります。 |
POST | /{endpointId}/deliveries/{deliveryId}/retry | 失敗した配信を 1 つ再試行します。 |
TypeScript SDK では、次を使用します。 kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery()、そして .delete()。返されたエンドポイントは scope: "workspace" 管理者が管理するエンドポイントの場合、または scope: "connection" 管理者以外の認証情報で登録した場合。次を保存してください： secret 作成またはローテーションによって直ちに返されます。後で読み取っても公開されることはありません。
Webhook イベントの種類
パブリック API は、現在のリストを次の場所で公開します。
https://api.kanera.app/webhook-event-types
| エリア | イベントの種類 |
|---|---|
| リスト | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| 基板セパレーター | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| カスタムフィールド | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| カスタムフィールドのオプション | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| カード | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| カードのカスタムフィールド | card:customFieldValue:set, card:customFieldValue:cleared |
| カードのラベルと譲受人 | card:labels:set, card:assignees:set |
| カード付属品 | card:attachment:created, card:attachment:deleted |
| カードのチェックリスト | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| カードのチェックリスト項目 | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| ワークスペースカードのラベル | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| コメント | comment:created, comment:updated, comment:deleted |
| コメントの反応 | comment:reaction:added, comment:reaction:removed |
| カードフィード | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| ボード | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| ボードメンバー | board:member:added, board:member:removed |
| ワークスペース | workspace:updated, workspace:deleted |
| ワークスペースのメンバー | workspace:member:added, workspace:member:updated, workspace:member:removed |
| ユーザー | user:profile:updated |
| ノート | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| エージェントの実行 | agentRun:started, agentRun:updated |
ペイロード形式
Kanera は、安定したエンベロープとイベント固有の JSON オブジェクトとして各 Webhook を送信します。 data.
| フィールド | 意味 |
|---|---|
id | 一意の Webhook イベント ID。これは一致します X-Kanera-Event-Id. |
type | イベントの種類: card:created. |
workspaceId | イベントが発生したワークスペース。 |
boardId | イベントがボードスコープの場合、イベントが発生したボード。 |
cardId | イベント ペイロードがカードを識別する場合、イベントに関与するカード。 |
occurredAt | イベント発生時の ISO 8601 タイムスタンプ。 |
data | 完全なイベント ペイロード。形状は以下に依存します type 対応するリアルタイム イベント ペイロードと一致します。 |
エージェントが実行するイベントは、 { boardId, cardId, run } で data、ここで run はエージェントの完全な実行です: agentName、 userId それはのために働きます、 status, title, summary, externalUrl、そしてその startedAt, heartbeatAt、そして endedAt タイムスタンプ。 agentRun:updated すべてのハートビートとステータス変化で起動するため、ハンドラーにキーを設定します。 run.status それぞれの配信を新しい作品として扱うのではなく、心臓の鼓動が止まるような走りが決勝戦としてやってくる agentRun:updated 次を使用： status: "stalled".
例 card:created ペイロード:
{
"id": "7e5c982a-e6c9-4ea7-9647-b14fe73ed50a",
"type": "card:created",
"workspaceId": "a069fd45-3bb3-4928-bac9-cb574a050d20",
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"cardId": "70c39cef-1aec-44e6-a8f5-f36f765a818d",
"occurredAt": "2026-05-28T12:34:56.000Z",
"data": {
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"card": {
"id": "70c39cef-1aec-44e6-a8f5-f36f765a818d",
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"listId": "3bb3c1b3-8fc7-4807-854d-2d5ff62df147",
"title": "Prepare kickoff agenda",
"position": "1000.0000000000"
}
}
}
Webhook配信
Kanera は Webhook 配信を JSON として送信し、リクエストの検証に使用できるヘッダーを含めます。
| ヘッダー | 意味 |
|---|---|
X-Kanera-Event-Id | 一意のイベント ID。 |
X-Kanera-Timestamp | 秒単位の Unix タイムスタンプ。 |
X-Kanera-Signature | sha256= さらに HMAC-SHA256 署名が追加されます。 |
署名は次のように計算されます。
${timestamp}.${rawBody}
Webhookエンドポイントのシークレットを使用します。
Webhook 配信は、エンドポイントが 2xx 以外のステータスを返した場合、またはエンドポイントに到達できない場合に再試行されます。 Kanera は配信履歴を記録するため、ワークスペース API 設定から失敗の確認、配信の再試行、宛先の一時停止、シークレットのローテーションを行うことができます。
Webhook 署名を検証する
ペイロードを信頼する前に署名を検証してください。
の TypeScript SDK これを自動的に実行し、ハンドラーがチェックを忘れないようにブール値を返すのではなくスローします。
import { parseWebhook } from "@kanera/sdk";
app.post("/kanera/webhook", express.raw({ type: "application/json" }), async (req, res) => {
const event = await parseWebhook({
secret: process.env.KANERA_WEBHOOK_SECRET!,
payload: req.body, // the raw bytes
headers: req.headers,
});
// Handle event.type, event.workspaceId, event.boardId, event.cardId, and event.data.
res.sendStatus(204);
});
自分で確認するには、HMAC を比較してください。 {timestamp}.{body} 一定時間内に。長さのチェックに注意してください。 crypto.timingSafeEqual 2つのバッファーの長さが異なる場合に例外を投げます。この長さは攻撃者が操作できます。
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/kanera/webhook", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.header("X-Kanera-Timestamp") ?? "";
const signature = req.header("X-Kanera-Signature") ?? "";
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.KANERA_WEBHOOK_SECRET!)
.update(`${timestamp}.${req.body.toString("utf8")}`)
.digest("hex");
const received = Buffer.from(signature);
const digest = Buffer.from(expected);
if (received.length !== digest.length || !crypto.timingSafeEqual(received, digest)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body.toString("utf8"));
// Handle event.type, event.workspaceId, event.boardId, event.cardId, and event.data.
res.sendStatus(204);
});
常に生のリクエスト本文に対して検証してください。フレームワークが検証前に JSON を解析すると、署名チェックが失敗するか、信頼性が低くなる可能性があります。
兼良も送る X-Kanera-Timestamp そして X-Kanera-Event-Id。配信が再試行される可能性があるため、タイムスタンプが現在から数分を超えている配信を拒否してバウンド再生を行い、イベント ID を使用してハンドラーを冪等にします。
関連するアウトバウンドオプション
Webhook は汎用パスです。特定の対象者向けに、より狭い 2 つのオプションが存在します。
| パス | 観客 | ペイロード | どこに設定するか | プラン |
|---|---|---|---|---|
| Webhook | 別のシステム | イベントカタログ全体にわたる署名付きJSON | ワークスペース設定 -> API | プロまたはトライアル |
| チャットの宛先 | チームチャンネル | Slack、Discord、Telegram、または Zulip 用にフォーマットされたメッセージ | ワークスペース設定 -> 統合 | プロまたはトライアル |
| 個人の配送チャネル | 1人 | 独自の通知用の ntfy、Gotify、または署名付き JSON | プロフィール設定 -> 通知 | プロまたはトライアル |
| MCP イベントのサブスクリプション | AI エージェントのホスト | エージェントが検証したコールバックへの署名付きカードとコメントの出現 | エージェントは MCP 経由でサブスクライブします。Kaneraには何もセットアップする必要はありません | すべてのプラン |
チャット宛先は Webhook エンドポイントとは別に管理され、Webhook リストには表示されないため、Webhook シークレットをローテーションしてもチャット宛先に影響を与えることはありません。
オートメーションの Webhook を呼び出す アクションはサブスクリプションベースではなくターゲットを絞ったものになります。送信します automation:webhook:called エンドポイントの通常とは関係なく、ルールで選択されたエンドポイントのみに送信されます。 eventTypes 同じ署名、再試行、配信履歴の動作を維持しながら、フィルターを実行します。参照 自動化.