Webhook を管理する

GDPR 規制に従ってユーザーのプライバシーを向上させるため、Bitbucket やその他の Atlassian Cloud 製品では個人データへのアクセスの管理方法を統一するために製品 API の更新を進めています。これらの API の変更は、アトラシアン製品で今後予定されている改善である、データの表示およびアクセスを許可するユーザーのより詳細な制御をサポートするために必要です。

The short summary is that username endpoints and username fields will stop being available on April 12, 2019, and we’re introducing some new data points that are available immediately to replace them. For more information, visit the API deprecation notice.

Webhook を使うことで、Bitbucket Cloud で特定のイベントが発生したときにサーバー (または外部サービス) にリクエストを送信するよう、Bitbucket Cloud を構成できます。Webhook の構成要素は次のとおりです。

  • 適用対象 - イベントを生成するリソース。現在、このリソースは Webhook を作成するリポジトリです。
  • 1 つ以上のイベント - デフォルトのイベントはリポジトリ プッシュですが、Webhook をトリガーできるイベントを複数選択できます。
  • URL - 設定した条件に一致するイベントが発生した場合に、Bitbucket がイベント ペイロードを送信するエンドポイント


Webhook を機能させるための作業として、Webhook の作成Webhook のトリガーの 2 段階の手順があります。イベント用の Webhook を作成すると、イベントが発生するたびに、Bitbucket はイベントについてのペイロード リクエストを指定した URL に送信します。そのため、Webhook は通知システムのようなものだと考えることができます。

Webhook に問題がある場合は、「Webhook のトラブルシューティング」を参照してください。

Webhook を使用するタイミング

Webhooks を使用して Bitbucket Cloud とアプリケーションを連携できます。次のような例があります:

  • ユーザーがリポジトリにコミットをプッシュするたびに CI サーバーにビルドを開始するよう通知する
  • ユーザーがコミットをプッシュしたり、プルリクエストを作成するたびに、アプリケーションで通知を表示する

Webhook のメリット

Webhook を使用しない場合、Bitbucket Cloud でのイベント発生を確認するには、API をポーリングする必要があります。ただし、API のポーリングは利便性が低く非効率な場合があり、エラーも発生しがちです。携帯電話での SMS メッセージの仕組みを考えてみてください。電話が通知を送信するため、5 分ごとにメッセージ アプリを確認して新着情報があるかどうかを確認する必要はありません。同様に、Webhook は通知のように機能するため、API で 1 分おきに同じアクティビティを確認する必要はありません。

Webhook の作成

Bitbucket Cloud または API から Webhook を作成できます。次の手順を使用して、Bitbucket のリポジトリで Webhook を作成します。リポジトリの管理者のみがリポジトリで Webhook を作成できます。

  1. Bitbucket で Webhook を追加したいリポジトリを開きます。
  2. 左側にある [設定] リンクをクリックします。
  3. [設定] ページのリンクから、[Webhooks] リンクをクリックします。
  4. [Webhook の追加] ボタンをクリックしてリポジトリに Webhook を作成します。[新しい Webhook の追加] ページが表示されます。

    • A. URL: Webhook 用サーバーの URL を入力します。
    • B. Webhook トリガー: Webhook をトリガーするイベントを選択します。
  5. [タイトル] に短い説明を入力します。
  6. アプリケーションまたはサーバーへの URL を入力します。
  7. (オプション) 保存後に Webhook をアクティブにしたくない場合は、[アクティブ] からチェックマークを外します。
  8. (オプション) 自己署名証明書を使用しているために証明書の検証を無効化したい場合は、[証明書の検証をスキップ] を選択します。

    自己署名証明書は本質的に安全でないため、証明書の検証を無効化しないことをお勧めします。自己署名証明書の使用の詳細については、次のセクションをお読みください。

  9. 必要に応じて、[トリガー] フィールドを更新します。
    既定の Webhook トリガーは、[リポジトリ プッシュ] フィールドで示される、リポジトリのプッシュです。Webhook トリガーを追加したり、別の操作でトリガーさせたい場合は、[トリガーの完全な一覧から選択] をクリックします。Webhook をトリガーできるすべてのイベント タイプの一覧が表示されます。

  10. Webhook に必要な情報をすべて入力した後、[保存] をクリックします。

API を使用して Webhook を作成するには、Bitbucket が期待する HTTP リクエストの形式と、Bitbucket がサーバーに返す HTTP 応答の形式を知っておく必要があります。これらのリクエストや応答の説明と例について、参考ドキュメントを参照してください。

また、ホワイトリストに追加する Bitbucket Cloud IP アドレスもご確認ください。

自己署名証明書を使用する場合

Webhook を作成する際、Bitbucket は証明書の検証をスキップするオプションを提供します。このオプションでは、イベント ペイロード リクエストを Webhook URL に送信する際に、証明書の検証を無効化できます。このオプションは、自己署名の SSL 証明書を使用している HTTPS エンドポイントで Webhook を受信する場合に使用できます。ただし、自己署名証明書は本質的に安全でないため、以下の場合を除いては証明書の検証を無効化しないことをお勧めします。

  • 公共の認証局が署名した有効な SSL 証明書をインストールできない。また、
  • セキュリティを考慮する必要がない Webhook である

HTTPS エンドポイントを使用すると、送信データは対称キーを使用して暗号化され、対称キー自体は SSL 証明書の公開キーを使用して暗号化されます。ただし、自己署名証明書を使用している場合、証明書は信頼できる証明局の署名を受けていないため、証明書を信頼できるものとみなすことができません。その結果、自己署名証明書を使用して HTTPS エンドポイント経由でデータを送信する場合、意図するサーバーと通信しているかどうかを把握することができません。つまり、証明書が検証されていない場合、不正な第三者がサーバーになりすまして MITM (介入者) 攻撃を実行できてしまうことになります。

可能であれば、証明書の検証を無効化しないことをお勧めします。初回のキー交換の間に双方の身元を確実に確認できる唯一の方法は、信頼できる証明局の SSL 証明書を取得しておくことです。これにより、Bitbucket から送信されたデータが、他の人物ではなく自分の証明書の公開キーを使用して正しく暗号化されることを確認できます。安価な SSL 証明書のオプションについては以下をご覧ください。

Webhook のトリガー

Webhook に関連付けられたイベントが発生すると、Bitbucket Cloud は、イベント ペイロードを含むリクエストを Webhook URL に送信します。

If you want your server to check that the payloads it receives are from Bitbucket, you may need to whitelist certain IP addresses. For more specific information, see What are the Bitbucket Cloud IP addresses I should use to configure my corporate firewall?

次のイベント用に Webhook を作成できます。

各イベント ペイロードの説明と例については、イベントのドキュメントを参照してください。

最終更新日 2019 年 4 月 26 日

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

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