Webhookの概要

Sursaは、重要な変更があるたびにイベントを記録します。カードが公開・検証・アーカイブされた、お知らせが読まれた、質問に回答がなかった、などです。イベントは2つの方法で受け取ることができ、両方を併用することもできます。

	Webhook	イベントフィード
方法	Sursaが、発生したイベントを1件ずつ自社のHTTPSのアドレスに送信します。	好きなときに`GET /v1/webhook-events`を読み込みます。
遅延	数秒。	ポーリングの頻度しだい。
必要なもの	公開されたHTTPSの受信サーバー。	`admin`ロールと`webhooks:manage`スコープを持つAPIキーだけ。
向いている用途	変更への対応：通知、同期、ワークフローの開始。	バッチジョブ、停止後の遅れの取り戻し、照合。

どちらも、同じIDを持つ同じイベントを伝えます。どのイベントも、それを購読したWebhookがあるかどうかにかかわらず、30日間フィードに保持されます。

イベント

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

フィールド	意味
`id`	イベントのID。`evt_`と32文字の16進数。すべての配信試行とフィードで同じです。
`type`	起きたこと。`<object>.<past-tense verb>`の形式です：`card.updated`、`access_request.resolved`。
`created_at`	変更が起きた日時（UTC）。
`api_version`	`data`が従うスキーマのAPIのバージョン。
`object`	イベントの対象となるオブジェクトの種類とID。
`data`	詳細。形はタイプによって異なり、イベントカタログに記載されています。
`data.previous_attributes`	`*.updated`イベントで、変更されたフィールドの以前の値。
`sequence`、`payload`、`test`	Webhookの配信だけに含まれます：そのWebhookへの配信順序での位置、ペイロードモード、テストイベントかどうか。

dataには、オブジェクトを参照できる人ならAPIで確認できる情報だけが入ります。アクセスリスト、他の人の権限、非表示のフィールドは決して含まれません。イベントの理由は、no_hits、restricted、index_failedのような短い中立的なコードです。

イベントタイプ

イベントは次の分野をカバーします。

分野	例
カード	`card.created`、`card.updated`、`card.published`、`card.archived`、`card.deleted`、`card.indexed`、`card.index_failed`
検証	`card.verified`、`card.unverified`、`verification.expired`、`verification.requested`
構造	`collection.created`、`folder.updated`
共同作業	`comment.created`、`draft.publish_requested`、`announcement.sent`、`announcement.read`
回答	`question.unanswered`、`question.feedback_created`、`access_request.created`
メンバーとアクセス	`user.created`、`user.deactivated`、`group.member_added`、`api_key.expiring`
ソースとインポート	`source.sync_completed`、`import.sync_completed`、`import.document_failed`
ジョブ	`job.completed`、`job.failed`、`export.ready`
Webhook	`webhook.endpoint_disabled`、`webhook.ping`

各イベントのスキーマと例を含む完全な一覧は、APIリファレンスのイベントカタログにあります。GET /v1/webhooks/catalogは、インストール環境で利用できるタイプを返します。

新しいイベントタイプは随時追加され、既存のイベントにはフィールドが加わります。イベントタイプの名前が変わったり、削除されたりすることはありません。受信サーバーは、知らないタイプとフィールドをスキップする必要があります。

受信の対象

Webhookがイベントを受信するのは、イベントのオブジェクトがそのWebhookから参照できる場合だけです。参照できるかどうかはAPIキーと同じく、ロール、データプロファイル、コレクションで決まります。supportコレクションに限定したWebhookが、financeのカードについてのイベントを受信することはありません。ユーザー、キー、ソース、インポート、ジョブ、エクスポート、料金と請求、アプリケーション、Webhook自体についてのイベントは、adminロールのWebhookにだけ送られます。

その範囲の中で、各Webhookは受信するイベントを選びます。

タイプで選ぶ（マスクを使用）：card.*はすべてのカードのイベント、*はすべてのイベント。
カードのイベントでは、コレクションとタグで選ぶ。

Webhookのペイロードモードは、full（dataを含むイベント。デフォルト）またはthin（dataを含まないイベント。受信サーバーは自分のキーを使ってAPIでオブジェクトを読み込み、常にその現在の状態を確認します）です。

配信の概要

イベントをJSONで送るHTTPSのPOSTです。Webhookのシークレットで2つの形式の署名が付きます：Standard Webhooks（webhook-signature）と、以前のX-KB-Signatureです。
10秒以内の2xxの応答はすべて成功です。
失敗した配信は、間隔を広げながら3日近く再試行されます。429または503のレスポンスのRetry-Afterは尊重されます。410はWebhookを無効にし、10回連続の失敗は再開されるまでWebhookを一時停止します。
1つのWebhookへの配信は、厳密に順序どおりに送られます。応答の遅いWebhookが、他のWebhookへの配信を遅らせることはありません。
同じイベントが複数回届くことがあります。重複はwebhook-idで取り除いてください。

Webhookを受信するでは、Node.js、Python、Goでの署名の検証を含め、受信サーバーの完全な例を順に説明しています。

Webhookの管理

作業	エンドポイント
Webhookを作成してシークレットを取得する	`POST /v1/webhooks`
受信先URL、イベント、状態を変更する	`PATCH /v1/webhooks/{webhook_id}`
テストイベントを送信する	`POST /v1/webhooks/{webhook_id}/test`
シークレットをローテーションする	`POST /v1/webhooks/{webhook_id}/rotate-secret`
一時停止中のWebhookを再開する	`POST /v1/webhooks/{webhook_id}/resume`
配信と応答を確認する	`GET /v1/webhooks/{webhook_id}/deliveries`
配信をもう一度送信する	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Webhookの管理には、adminロールとwebhooks:manageスコープを持つキー、または管理画面での管理者の操作が必要です。組織には最大20個のWebhookを登録できます。Webhookは組織のプランに含まれる機能です。プランに含まれていない場合、これらのエンドポイントはコードwebhooks.feature_disabledとともに403を返します。