Webhook を管理する
Webhooks provide a way to configure Bitbucket Data Center and Server to make requests to your server or another external service, whenever certain events occur. A webhook consists of:
- 1 つ以上のイベント – デフォルトのイベントはリポジトリ プッシュですが、Webhook をトリガーできるイベントを複数選択できます。
- URL – 設定した条件に一致するイベントが発生した場合に、Bitbucket がイベント ペイロードを送信するエンドポイント。
There are two stages to the webhook: Creating webhooks and Triggering webhooks. Once you've created a webhook for an event, every time that event occurs, Bitbucket sends a payload request that describes the event to the specified URL.
Webbhook に問題がある場合は、「Webhook のトラブルシューティング」を参照してください。
On this page:
Webhook を使用するタイミング
Use webhooks to integrate applications with Bitbucket. For example:
- ユーザーがリポジトリにコミットをプッシュするたびに 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 のメリット
Without webhooks, you need to poll the API if you want to detect when events occur in Bitbucket. However, polling the API is inconvenient, inefficient, and error-prone.
Webhook を使用すると、API で 1 分おきに同じアクティビティを確認する必要はなくなります。
Webhook シークレット
Webhook secrets are what Bitbucket use to authenticate the payload. The secret ensures that between Bitbucket and your endpoint, you're able to verify that the contents were not tampered with.
Combined with HTTPS, it helps ensure the message transmitted is the one that Bitbucket intended to send.
Webhook の保護
Webhook のシークレットを定義すると、各リクエストはハッシュ ベースのメッセージ認証コード (HMAC) で署名されます。
このアルゴリズムのデフォルトは、HMACSha256 です。ヘッダー X-Hub-Signature が定義され、HMAC が含まれます。
メッセージ ペイロードの妥当性を認証するため、受信側は、HMAC アルゴリズムのキーとしてシークレットを使用し、受信した本文に対して HMAC アルゴリズムを実行できます。
結果が一致しない場合、メッセージ ペイロードを変化させる原因となった転送に問題が発生したことを示している可能性があります。
Webhook の作成
You can create a webhook through Bitbucket, or with the API. Use the following steps to create a webhook on a repository in Bitbucket. Don't forget the administrators of a repository are the only users who can create a webhook on that repository.
- Webhook を追加するリポジトリを開きます。
- [リポジトリ設定] から、[Webhook] リンクをクリックします。
- Click the Create webhook button to create a webhook for the repository.
- [Webhook イベント]: Webhook をトリガーするイベントを選択します。
- [タイトル] に短い説明を入力し、アプリケーションまたはサーバーの URL を入力します。
(オプション) シークレット文字列を最大 255 文字で入力します。
- (オプション) 必要に応じて、[テスト接続] ボタンを使用します。
- 既定の Webhook イベントは、[リポジトリ プッシュ] フィールドで示される、リポジトリのプッシュです。
(オプション) 作成後に Webhook をアクティブにしたくない場合は、[アクティブ] からチェックマークを外します。
[作成] をクリックします。
To create a webhook using the API, you need to know the format of the HTTP request that Bitbucket expects and the format of the HTTP response that Bitbucket returns to your server.
Webhook のトリガー
When an event associated with a webhook occurs, Bitbucket sends a request to the webhook URL containing the event payload.
次のイベント用に Webhook を作成できます。
リポジトリ イベント
- プッシュ
- 最終変更日
- Forked
- コミットへのコメント追加時
- コミットのコメント編集時
- コミットでのコメント削除時
- Mirror synchronized
プル リクエスト イベント
- オープン時
- Source branch updated
- 最終変更日
- Reviewers updated
- 承認
- 未承認時
- 作業が必要な場合
- マージ
- 却下
- Deleted
- コメント追加時
- コメント編集時
- コメントの削除
Webhook のトラブルシューティング
Webhook をトリガーする操作を実行しても Webhook が機能しない場合、[イベント ログ] ページを使用して、問題について確認できます。
To view the event log and troubleshoot, navigate to the Webhooks page and select View details (from the Actions column) against the webhook that doesn't work.
最新のリクエスト結果 (Webhook イベント詳細など) をクリックして問題をトラブルシューティングします。
サーキット ブレーカー
To help protect your instance of Bitbucket, circuit breaking has been implemented in the Bitbucket webhooks system. This means badly behaving webhooks are skipped for a period of time if they are consistently failing.
既定では、Webhook が 5 回失敗すると、正常ではないとみなされ、スキップされます。
最初は短い期間 (10 秒) だけスキップされますが、失敗が続くと徐々に長期間スキップされるようになり、最大で 10 時間スキップされるようになります。
多数の webhook が動作している場合も webhook がスキップされる場合があります。250 の webhook が起動すると、それらが 250 以内になるまで以降のリクエストがスキップされます。
These limits are entirely configurable if your instance has different requirements. For more information, see Configuration properties.
If a webhook is being skipped, you can see so via the JMX metrics output by Bitbucket, or via the logs.