webhook の管理

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

Webhook を使用すると、Confluence で特定のイベントが発生した際に、アプリケーションやその他の外部サービスに通知することができます。たとえば Webhook を設定して、課題トラッカーを更新したり、チャット ツールで通知をトリガーしたりできます。

このページの内容

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 を作成するには、

  1. > [一般設定] >[Webhook] に移動します。
  2. Webhook のタイトルを入力します。
  3. アプリケーションまたはサーバーの URL を入力します。
  4. シークレットを入力します。これは、ユーザーが定義する最大 255 文字の文字列です。 
  5. [テスト接続] を選択して、アプリケーションまたはサーバーに接続できることを確認します。
  6. Webhook をトリガーするイベントを選択します。
  7. [アクティブ] を選択して、Webhook を今すぐ使用できるようにします。 
  8. [作成] を選択します。 

スクリーンショット: スペースの作成や削除時にチャット アプリケーションに通知する 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 以内になるまで以降のリクエストがスキップされます。

最終更新日: 2021 年 2 月 2 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.