Bitbucket Server で webhook を管理する
Webhook を使うことで、特定のイベントが発生したときにサーバーまたは外部サービスにリクエストを送信するよう、Bitbucket Server を構成できます。webhook の構成要素は次のとおりです。
- 1 つ以上のイベント – デフォルトのイベントはリポジトリ プッシュですが、Webhook をトリガーできるイベントを複数選択できます。
- URL – 設定した条件に一致するイベントが発生した場合に、Bitbucket がイベント ペイロードを送信するエンドポイント。
Webhook のステージには、Webhook の作成と Webhook のトリガーの 2 つがあります。イベント用の Webhook を作成すると、イベントが発生するたびに、Bitbucket はイベントについてのペイロード リクエストを指定した URL に送信します。
Webbhook に問題がある場合は、「Webhook のトラブルシューティング」を参照してください。
On this page:
Webhook を使用するタイミング
Webhook を使用して Bitbucket Server とアプリケーションを連携できます。例:
- ユーザーがリポジトリにコミットをプッシュするたびに CI サーバーにビルドを開始するよう通知する
- ユーザーがコミットをプッシュしたり、プルリクエストを作成するたびに、アプリケーションで通知を表示する
- Every time a user pushes commits to a repository, and a mirror synchronizes those changes, you may want to notify your continuous integration system to start a build.
Webhook のメリット
Webhook を使用しない場合、Bitbucket Server でイベントが発生したタイミングを検出するには API をポーリングする必要があります。ただし、API のポーリングは利便性が低く非効率な場合があり、エラーも発生しがちです。
Webhook を使用すると、API で 1 分おきに同じアクティビティを確認する必要はなくなります。
Webhook シークレット
Webhook シークレットは、Bitbucket Server がペイロードを認証するのに使用するものです。シークレットによって、Bitbucket Server とエンドポイント間で、コンテンツが改ざんされていないことを確認できるようになります。
HTTPS と組み合わせると、転送されたメッセージが Bitbucket Server が送信しようとしたものであることを保証できます。
Webhook の保護
Webhook のシークレットを定義すると、各リクエストはハッシュ ベースのメッセージ認証コード (HMAC) で署名されます。
このアルゴリズムのデフォルトは、HMACSha256 です。ヘッダー X-Hub-Signature が定義され、HMAC が含まれます。
メッセージ ペイロードの妥当性を認証するため、受信側は、HMAC アルゴリズムのキーとしてシークレットを使用し、受信した本文に対して HMAC アルゴリズムを実行できます。
結果が一致しない場合、メッセージ ペイロードを変化させる原因となった転送に問題が発生したことを示している可能性があります。
Webhook の作成
Bitbucket Server または API から Webhook を作成できます。次の手順を使用して、Bitbucket のリポジトリで Webhook を作成します。リポジトリの管理者のみがリポジトリで Webhook を作成できます。
- Webhook を追加するリポジトリを開きます。
- [リポジトリ設定] から、[Webhook] リンクをクリックします。
- Click the Create webhook button to create a webhook for the repository.
- [Webhook イベント]: Webhook をトリガーするイベントを選択します。
- [タイトル] に短い説明を入力し、アプリケーションまたはサーバーの URL を入力します。
(オプション) シークレット文字列を最大 255 文字で入力します。
- (オプション) 必要に応じて、[テスト接続] ボタンを使用します。
- 既定の Webhook イベントは、[リポジトリ プッシュ] フィールドで示される、リポジトリのプッシュです。
(オプション) 作成後に Webhook をアクティブにしたくない場合は、[アクティブ] からチェックマークを外します。
[作成] をクリックします。
API を使用して Webhook を作成するには、Bitbucket が期待する HTTP リクエストの形式と、Bitbucket がサーバーに返す HTTP 応答の形式を知っておく必要があります。
Webhook のトリガー
Webhook に関連付けられたイベントが発生すると、Bitbucket Server は、イベント ペイロードを含むリクエストを Webhook URL に送信します。
次のイベント用に Webhook を作成できます。
リポジトリ イベント
- プッシュ
- 最終変更日
- Forked
- コミットへのコメント追加時
- コミットのコメント編集時
- コミットでのコメント削除時
- Mirror synchronized
プル リクエスト イベント
- オープン時
- Source branch updated
- 最終変更日
- Reviewers updated
- 承認
- 未承認時
- 作業が必要な場合
- マージ
- 却下
- Deleted
- コメント追加時
- コメント編集時
- コメントの削除
Webhook のトラブルシューティング
Webhook をトリガーする操作を実行しても Webhook が機能しない場合、[イベント ログ] ページを使用して、問題について確認できます。
リポジトリ設定の [イベント詳細] では、[アクション] 列から [詳細を表示] をクリックして、トラブルシューティング用のイベント ログにアクセスできます。
最新のリクエスト結果 (Webhook イベント詳細など) をクリックして問題をトラブルシューティングします。
サーキット ブレーカー
Bitbucket Server のインスタンスの保護を支援するため、Bitbucket Webhook システムにはサーキット ブレーカーが実装されています。これは、不正な動作をしている Webhook が一貫して失敗している場合、しばらくの間それらがスキップされることを意味しています。
既定では、Webhook が 5 回失敗すると、正常ではないとみなされ、スキップされます。
最初は短い期間 (10 秒) だけスキップされますが、失敗が続くと徐々に長期間スキップされるようになり、最大で 10 時間スキップされるようになります。
多数の webhook が動作している場合も webhook がスキップされる場合があります。250 の webhook が起動すると、それらが 250 以内になるまで以降のリクエストがスキップされます。
これらの制限は、インスタンスに異なる要件がある場合、完全に構成可能です。詳細については、「Bitbucket Server プロパティ」を参照してください。
webhook がスキップされると、Bitbucket による JMX メトリック出力またはログからそれを確認できます。