webhook の管理
Webhook を使用すると、Confluence で特定のイベントが発生した際に、アプリケーションやその他の外部サービスに通知することができます。たとえば Webhook を設定して、課題トラッカーを更新したり、チャット ツールで通知をトリガーしたりできます。
On this page:
webhook の構成要素は次のとおりです。
- 1 つ以上のイベント – ページの作成やスペースの削除など。Webhook をトリガーするイベントを複数選択できます。
- URL – 設定した条件に一致するイベントが発生した場合に、Confluence がイベント ペイロードを送信するエンドポイント。
作成すると、Confluence はこれらのイベントをリッスンし、指定した URL に JSON 形式のイベント ペイロードを送信します。
Webhook の保護
Confluence は、Webhook シークレットを使用してペイロードを認証します。HTTPS と組み合わせると、転送されたメッセージが Confluence が送信しようとしたものであり、コンテンツが改ざんされていないことを保証できます。
Webhook のシークレットを定義すると、各リクエストはハッシュ ベースのメッセージ認証コード (HMAC) で署名されます。 このアルゴリズムのデフォルトは、HMACSha256 です。ヘッダー X-Hub-Signature が定義され、HMAC が含まれます。
メッセージ ペイロードの妥当性を認証するため、受信側は、HMAC アルゴリズムのキーとしてシークレットを使用し、受信した本文に対して HMAC アルゴリズムを実行できます。結果が一致しない場合は、転送に問題があり、メッセージ ペイロードが変更された可能性があります。
新しい Webhook を作成する
Webhook を作成するには、Confluence 管理者またはシステム管理者グローバル権限が必要です。
新しい Webhook を作成するには、
> [一般設定] >[Webhook] に移動します。- Webhook のタイトルを入力します。
- アプリケーションまたはサーバーの URL を入力します。
- シークレットを入力します。これは、ユーザーが定義する最大 255 文字の文字列です。
- [テスト接続] を選択して、アプリケーションまたはサーバーに接続できることを確認します。
- Webhook をトリガーするイベントを選択します。
- [アクティブ] を選択して、Webhook を今すぐ使用できるようにします。
- [作成] を選択します。
スクリーンショット: スペースの作成や削除時にチャット アプリケーションに通知する Webhook の作成。
Webhook は、API を使用して作成することもできます。Confluence 開発者ドキュメントの「Webhook」を参照してください。
Webhook のトリガー
次のイベントでトリガーされる Webhook を設定できます。
| イベント | トリガーされるタイミング |
|---|---|
| attachment_created | ページやブログ投稿へのファイルの添付 |
| attachment_removed | 添付ページからのファイルの削除 (ごみ箱への送信) (ファイル履歴からバージョンが削除された場合にはトリガーされません) |
| attachment_restored | ごみ箱からのファイルの復元 |
| attachment_trashed | ごみ箱からのファイルの完全削除 |
| attachment_updated | 新しいファイル バージョンの直接のアップロード、またはファイルの編集 |
| blog_created | ブログ投稿の公開 |
| blog_removed | ブログ投稿の削除 (ごみ箱への送信) |
| blog_restored | ごみ箱からのブログ投稿の復元 |
| blog_trashed | ごみ箱からのブログ投稿の完全削除 |
| blog_updated | ブログ投稿の編集 |
| blueprint_page_created | ブループリントからのページの作成 (ミーティング議事録、意思決定、ハウツーなど) |
| comment_created | ページ コメント、インライン コメント、ファイル コメントの作成 |
| comment_removed | ページ コメント、インライン コメント、ファイル コメントの削除 |
| comment_updated | ページ コメント、インライン コメント、ファイル コメントの編集 |
| content_created | ページ、ブログ投稿、添付 (ファイル)、コメント (ページ、インライン、ファイル)、その他のファイル (スペース ロゴなど) の作成やアップロード。 |
| content_restored | ごみ箱からのページ、ブログ投稿、添付 (ファイル) の復元 |
| content_trashed | ごみ箱からのページ、ブログ投稿、添付 (ファイル) の完全削除 |
| content_updated | ページ、ブログ投稿、添付 (ファイル)、コメント (ページ、インライン、ファイル) の編集。 |
content_permissions_updated | ページやブログ記事に対する表示制限や編集制限の適用または削除 |
group_created | 新しいグループの作成 |
| group_removed | グループの削除 |
| label_added | ページ、ブログ投稿、スペースへの既存のラベルの適用 |
| label_created | ラベルの初回の追加 (まだ存在していなかったもの) |
| label_deleted | ラベルが最後のページ、ブログ、投稿、またはスペースから削除され、存在しなくなった |
| label_removed | ページ、ブログ投稿、スペースからのラベルの削除 |
page_children_reordered | デフォルトのページ順序をアルファベット順に変更 ([スペース ツール] > [ページ順序の変更] タブ) (ページをドラッグしたり、ページを移動したりしてページの順序を変更したときにはトリガーされません) |
| page_created | ページの初回の公開 (テンプレートやブループリントから作成されたページを含む) |
| page_moved | ページ ツリー内の別の位置、別の親ページ、または別のスペースへのページの移動 |
| page_removed | ページが削除された (ゴミ箱の中) |
| page_restored | ごみ箱からのページの復元 |
| page_trashed | ごみ箱からのページの完全削除 |
| page_updated | ページの編集 (未公開の変更が公開された時点でトリガー) |
| space_created | 新しいスペースが作成された |
| space_logo_updated | スペースのロゴとして使用するための新しいファイルのアップロード |
| space_permissions_updated | スペース権限の変更 ([スペース ツール] > [権限] タブ) (権限の検査を使用してスペース権限を編集する場合はトリガーされません) |
| space_removed | スペースの削除 |
space_updated | スペースの詳細 (タイトル、説明、ステータス) の更新 ([スペース ツール] > [権限] タブ) |
theme_enabled | 特定のテーマまたは既定のテーマがサイト全体に適用されます |
user_created | 新しいユーザー アカウントの作成 |
| user_deactivated | ユーザー アカウントの無効化 |
| user_followed | 誰かがユーザーをフォローしている |
| user_reactivated | 無効化されたユーザー アカウントの有効化 |
| user_removed | ユーザー アカウントの削除 |
イベント ペイロード
以下は、page_trashed イベントのイベント ペイロードの例です。これは、エンドポイントに送信された、JSON 形式の生データです。
{
"timestamp":1596182511300,
"event":"page_trashed",
"userKey":"ff80818154ec9913015501e194f601d8",
"page":{
"id":309264476
}
}コンテンツのほとんどが ID で構成されていることがわかります。これは、サードパーティのサービスによって識別可能な情報が保存されたり、表示権限を得ていないユーザーに漏洩したりすることがないようにするためです。
受信したら、REST API を使用してこれらの ID を解釈することができます。「Confluence Server Rest API」を参照してください。
サーキット ブレーカー
Confluence サイトを保護するために、失敗が繰り返された Webhook は一定期間スキップされます。初期設定では、Webhook が 5 回失敗すると正常ではないとみなされ、最初は 10 秒間スキップされます。引き続き失敗すると、期間が徐々に長くなり、最大 10 時間になります。
多数の webhook が動作している場合も webhook がスキップされる場合があります。500 の webhook が起動すると、それらが 500 以内になるまで以降のリクエストがスキップされます。