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 Data Center Rest API」を参照してください。
Circuit breaking
Confluence サイトを保護するために、失敗が繰り返された Webhook は一定期間スキップされます。初期設定では、Webhook が 5 回失敗すると正常ではないとみなされ、最初は 10 秒間スキップされます。引き続き失敗すると、期間が徐々に長くなり、最大 10 時間になります。
A webhook may also be skipped if there are too many webhooks in flight. If there are 500 webhooks being invoked, further requests will be skipped until the number in flight drops below 500.