Webhook を管理する
In order to improve user privacy in accordance with GDPR regulations, Bitbucket and other Atlassian Cloud products are updating our product APIs to consolidate how we manage access to personal data. These API changes are necessary to support upcoming improvements to Atlassian products that give users greater control over who can see and access their data.
username エンドポイントと username フィールドの提供は 2019 年 4 月 12 日に廃止する予定です。アトラシアンではこれらを置き換えるため、すぐに使用できる複数の新しいデータ ポイントを導入します。詳細は、API の廃止のお知らせを参照してください。
Webhooks provide a way to configure Bitbucket Cloud to make requests to your server (or another external service) whenever certain events occur in Bitbucket Cloud. A webhook consists of:
- 適用対象 - イベントを生成するリソース。現在、このリソースは Ｗebhook を作成するリポジトリです。
- 1 つ以上のイベント - デフォルトのイベントはリポジトリ プッシュですが、Webhook をトリガーできるイベントを複数選択できます。
- URL - 設定した条件に一致するイベントが発生した場合に、Bitbucket がイベント ペイロードを送信するエンドポイント。
Webhook を機能させるための作業として、Webhook の作成と Webhook のトリガーの 2 段階の手順があります。イベント用の Webhook を作成すると、イベントが発生するたびに、Bitbucket はイベントについてのペイロード リクエストを指定した URL に送信します。そのため、Webhook は通知システムのようなものだと考えることができます。
Webhook に問題がある場合は、「Webhook のトラブルシューティング」を参照してください。
Webhook を使用するタイミング
Use webhooks to integrate applications with Bitbucket Cloud, for example:
- ユーザーがリポジトリにコミットをプッシュするたびに CI サーバーにビルドを開始するよう通知する
- ユーザーがコミットをプッシュしたり、プルリクエストを作成するたびに、アプリケーションで通知を表示する
Webhook のメリット
Without webhooks, if you want to detect when events occur in Bitbucket Cloud, you need to poll the API. However, polling the API is inconvenient, inefficient, and error-prone. Consider how SMS messages work on mobile phones. You don't have to check your messages every 5 minutes to see if you have a text because your phone sends you a notification. In the same way, webhooks work like the notification so that the API does not have to check for the same activity every minute.
Webhook を作成する
You can create a webhook through Bitbucket Cloud or with the API. Use the following steps to create a webhook on a repository in Bitbucket. The administrators of a repository are the only users who can create a webhook on that repository.
リポジトリあたり最大 50 件の Webhook を作成できます。
- Bitbucket で Webhook を追加したいリポジトリを開きます。
- 左側にある [設定] リンクをクリックします。
- [設定] ページのリンクから、[Webhooks] リンクをクリックします。
- [Webhook の追加] ボタンをクリックしてリポジトリに Webhook を作成します。[新しい Webhook の追加] ページが表示されます。
- A. URL: Webhook 用サーバーの URL を入力します。
- B. Webhook トリガー: Webhook をトリガーするイベントを選択します。
- [タイトル] に短い説明を入力します。
- アプリケーションまたはサーバーへの URL を入力します。
- (オプション) 保存後に Webhook をアクティブにしたくない場合は、[アクティブ] からチェックマークを外します。
(オプション) 自己署名証明書を使用しているために証明書の検証を無効化したい場合は、[証明書の検証をスキップ] を選択します。
自己署名証明書は本質的に安全でないため、証明書の検証を無効化しないことをお勧めします。自己署名証明書の使用の詳細については、次のセクションをお読みください。
必要に応じて、[トリガー] フィールドを更新します。
既定の Webhook トリガーは、[リポジトリ プッシュ] フィールドで示される、リポジトリのプッシュです。Webhook トリガーを追加したり、別の操作でトリガーさせたい場合は、[トリガーの完全な一覧から選択] をクリックします。Webhook をトリガーできるすべてのイベント タイプの一覧が表示されます。Webhook に必要な情報をすべて入力した後、[保存] をクリックします。
API を使用して Webhook を作成するには、Bitbucket が期待する HTTP リクエストの形式と、Bitbucket がサーバーに返す HTTP 応答の形式を知っておく必要があります。これらのリクエストや応答の説明と例について、参考ドキュメントを参照してください。
また、許可リストに追加する Bitbucket Cloud IP アドレスを確認しておく必要がある場合があります。
If you use self-signed certificates
Webhook を作成する際、Bitbucket は証明書の検証をスキップするオプションを提供します。このオプションでは、イベント ペイロード リクエストを Webhook URL に送信する際に、証明書の検証を無効化できます。このオプションは、自己署名の SSL 証明書を使用している HTTPS エンドポイントで Webhook を受信する場合に使用できます。ただし、自己署名証明書は本質的に安全でないため、以下の場合を除いては証明書の検証を無効化しないことをお勧めします。
- 公共の認証局が署名した有効な SSL 証明書をインストールできない。また、
- セキュリティを考慮する必要がない Webhook である
HTTPS エンドポイントを使用すると、送信データは対称キーを使用して暗号化され、対称キー自体は SSL 証明書の公開キーを使用して暗号化されます。ただし、自己署名証明書を使用している場合、証明書は信頼できる証明局の署名を受けていないため、証明書を信頼できるものとみなすことができません。その結果、自己署名証明書を使用して HTTPS エンドポイント経由でデータを送信する場合、意図するサーバーと通信しているかどうかを把握することができません。つまり、証明書が検証されていない場合、不正な第三者がサーバーになりすまして MITM (介入者) 攻撃を実行できてしまうことになります。
可能であれば、証明書の検証を無効化しないことをお勧めします。初回のキー交換の間に双方の身元を確実に確認できる唯一の方法は、信頼できる証明局の SSL 証明書を取得しておくことです。これにより、Bitbucket から送信されたデータが、他の人物ではなく自分の証明書の公開キーを使用して正しく暗号化されることを確認できます。安価な SSL 証明書のオプションについては以下をご覧ください。
- Let's Encrypt: 無料 SSL 証明書を提供
- Instant SSL by Comodo: 90 日間の無料トライアルあり
Webhook を保護する
Bitbucket webhooks work by sending an HTTP POST request to the customer service at a particular URL. It's important that you protect your service from potential attacks. As a workaround, you could allowlist the Bitbucket IPs to restrict who can access your webhook resource.
Check out the list of Bitbucket IPs.
Webhook をトリガーする
When an event associated with a webhook occurs, Bitbucket Cloud sends a request to the webhook URL containing the event payload.
受信するペイロードが Bitbucket から送られたものかどうかをサーバーで確認したい場合、特定の IP アドレスを許可リストに追加する必要がある場合があります。詳しくは、「会社ファイアウォールを構成する際に、どの Bitbucket Cloud IP アドレスを使用する必要がありますか?」を参照してください。
次のイベント用に Webhook を作成できます。
各イベント ペイロードの説明と例については、イベントのドキュメントを参照してください。