ウェブフック管理

Classic/VPC環境で利用できます。

ウェブフックを利用すると、SourceCommitリポジトリで発生する各種イベントに対して後処理を行うことができます。NAVERクラウドプラットフォームの Cloud Functionsサービスと連携したり、特定の URLをウェブフックと連携することで、必要なイベントデータを受け取り、ビジネスロジックを処理できます。

以下のように様々な方式でウェブフックを活用できます。

• コードの変更を検知し、SourceBuild、SourceDeploy、SourcePipelineと CI/CDを連携
• Cloud Functionsサービスの Triggerと連携して Proxy Serverを管理せずに、リポジトリイベントに対する後処理ロジックを実行
• コミットプッシュやフルリクエスト作成通知を通じてコードレビュー時間を短縮
• FileSaferのマルウェアスキャン結果をすぐに受信
• LFSを通じた Fileロック/ロック解除有無をすぐに受信

ウェブフック管理

ウェブフックを利用するには、先にウェブフックを呼び出した時にイベントを転送する連携対象を指定してウェブフックを作成します。

ウェブフック作成

ウェブフックを作成する方法は次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > Developer Tools > SourceCommitメニューを順にクリックします。
2. SourceCommit画面でリポジトリを選択した後、 [コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
3. リポジトリ詳細機能画面で [Hooks] タブをクリックします。
   
4. [作成] ボタンをクリックします。
   
5. 作成するウェブフックの名前と説明を入力します。
   • ウェブフックの名前は英数字、記号「-」、「_」を使用して50文字以内で入力でき、既に作成されたウェブフックと同じ名前は入力不可能
   • 説明は300文字以内を入力可能
6. ウェブフックを呼び出すイベントタイプを選択します。
   • ウェブフックが属するリポジトリ内で当該イベントが発生すると、ウェブフックが呼び出されます。
   • イベントタイプに関する詳細は、ウェブフックイベントリストをご参照ください。
7. ウェブフックと連携する対象を追加します。イベントが発生してウェブフックが呼び出されると、連携対象を通じてデータを転送します。
   対象タイプによって対象を追加する方法が異なります。以下のガイドをご参照ください。
   • Cloud Functions連携対象を追加
   • URL連携対象を追加

Cloud Functions連携対象を追加

1. 対象タイプに Cloud Functionsを選択します。
2. [トリガー作成] ボタンをクリックして新規トリガーを作成します。
   
   • トリガー作成に関する詳細は、SourceCommit Trigger ご利用ガイドをご参照ください。
   • Cloud Functionsサービスを通じて SourceCommitトリガーを既に作成している場合、このステップは省略できます。
3. ウェブフック作成画面のトリガーリストからウェブフックと連携するトリガーを選択します。
4. 選択したトリガーの有効化有無を選択します。
   • リポジトリ内にイベントが発生してウェブフックが呼び出されると、選択したトリガーのうち、有効化有無が ONになっているトリガーのみ実行されます。
     
5. ウェブフック作成画面の [作成] ボタンをクリックしてウェブフックを作成します。

URL連携対象を追加

1. 対象タイプに URLを選択します。
   
2. 連携する URLと Content Type、Secretを入力します。
   • URL: 2000文字以内で入力でき、外部からの通信が可能なアドレスである必要がある(必須)
   注意

   • URL対象が HTTP status 3XXを返却する場合、リダイレクトをサポートしません。
   • Content Type: application/json、application/x-www-form-urlencodedの中から選択(必須)
   参考

   • application/json: request bodyデータとして JSON payloadをすぐに転送
   • application/x-www-form-urlencoded: 「payload」 keyに対する valueとして JSON payloadを転送
   • Secret(選択)
     • ウェブフック呼び出しが SourceCommitサービスから呼び出されたことを保証し、データが途中で改ざんされるのを防ぐためである
     • ウェブフック呼び出し時に request bodyを Secret keyに Hmac SHA256暗号化した値が 「x-ncp-sourcecommit-signature-v1」 ヘッダを通じて転送される(例)
     • 200文字以内で入力可能
3. URLの有効化有無を決定し、 [追加] ボタンをクリックして URLを作成します。
   • リポジトリ内にイベントが発生してウェブフックが呼び出されると、選択した URLのうち、有効化有無が ONになっている URLのみにデータが転送されます。
4. ウェブフック作成画面の [作成] ボタンをクリックしてウェブフックを作成します。

ウェブフックの設定変更

必要に応じて、ウェブフック作成時に入力した説明文とイベントタイプ、連携対象情報を変更できます。

ウェブフックの設定を変更する方法は次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > Developer Tools > SourceCommitメニューを順にクリックします。
2. SourceCommit画面でリポジトリを選択した後、 [コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
3. リポジトリ詳細機能画面で [Hooks] タブをクリックします。
4. [変更] ボタンをクリックします。
5. ウェブフックの設定を変更した後、 [適用] ボタンをクリックします。
   • ウェブフック設定時に入力する内容に関する詳細は、ウェブフック作成をご参照ください。

ウェブフック削除

ウェブフックの呼び出しが不要になった場合は、ウェブフックを削除できます。
ウェブフックを削除する方法は次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > Developer Tools > SourceCommitメニューを順にクリックします。
2. SourceCommit画面でリポジトリを選択した後、 [コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
3. リポジトリ詳細機能画面で [Hooks] タブをクリックします。
4. 保有しているウェブフックリストから削除するウェブフックを選択し、 [削除] ボタンをクリックします。
5. 削除確認のポップアップで最終的に [削除] ボタンをクリックします。

ウェブフック呼び出し結果の確認

ウェブフック連携対象ごとに呼び出し結果を確認できます。

• Cloud Functions連携対象の呼び出し結果を確認
• URL連携対象の呼び出し結果を確認

Cloud Functions連携対象の呼び出し結果を確認

連携対象が Cloud Functionsのウェブフックは、Cloud Functionsサービスコンソールで呼び出し結果を確認できます。

1. NAVERクラウドプラットフォームコンソールで、 > Services > Developer Tools > SourceCommitメニューを順にクリックします。
2. SourceCommit画面でリポジトリを選択した後、 [コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
3. リポジトリ詳細機能画面で [Hooks] タブをクリックします。
4. 確認したいウェブフックの [対象情報] カラム内のトリガー名をクリックして、Cloud Functionサービスコンソールに移動します。
   
   • トリガー呼び出し結果に関する詳細は、トリガーモニタリングガイドをご参照ください。

URL連携対象の呼び出し結果を確認

連携対象が URLのウェブフックは、ウェブフックリスト画面で [呼び出し結果] ボタンをクリックして確認できます。

1. NAVERクラウドプラットフォームコンソールで、 > Services > Developer Tools > SourceCommitメニューを順にクリックします。
2. SourceCommit画面でリポジトリを選択した後、 [コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
3. リポジトリ詳細機能画面で [Hooks] タブをクリックします。
4. 呼び出し結果を確認する URLタイプのウェブフックを選択した後、 [呼び出し結果] ボタンをクリックします。
   
   • 対象タイプ: ウェブフック対象タイプ(現在 URLのみサポート)
   • エンドポイント: ウェブフック対象 URL
   • 呼び出し時間: ウェブフックの呼び出し時間
   • ステータス: 呼び出しの成功・失敗の有無
5. 詳細な呼び出し結果を確認するには、 [見る] ボタンをクリックします。
   
   • リクエスト情報
     • リクエストヘッダ: ウェブフック呼び出し時の URL、Method、Headersの情報
     • リクエストボディ: ウェブフック呼び出し時に転送した Body情報
   • レスポンス情報
     • レスポンスステータスコード: ウェブフック呼び出し後にレスポンスを受けた HTTP Status Code
     • レスポンスヘッダ: ウェブフック呼び出し後にレスポンスを受けた Headers
     • レスポンスボディ: ウェブフック呼び出し後にレスポンスを受けた Body

URL対象ウェブフックデータの受信

URL対象のウェブフックデータを受信した後、secret値と「x-ncp-sourcecommit-signature-v1」ヘッダを用いて改ざんの有無を検証し、その結果を出力するユースケースを紹介します。

1. ウェブフック作成と URL連携対象を追加を参照して、以下のような内容でウェブフックを作成します。
   
   参考

   • URLウェブフックデータ転送時の HTTP Methodは POSTです。
   • ウェブフック呼び出し時に request bodyを Secret keyに Hmac SHA256暗号化した値が 「x-ncp-sourcecommit-signature-v1」 ヘッダを通じて転送されます。
   • Secret値が空白の場合、 「x-ncp-sourcecommit-signature-v1」 ヘッダは提供されません。
2. ユーザーのウェブサーバでウェブフックデータを受信できるように準備します。
   注意

   • secret値は外部に漏れないよう、保管に注意が必要です。以下のコードは参考目的のみで提供されます。

• Spring boot

  @RestController
  public class SampleController {
  
      @PostMapping("/test")
      public String test(
              @RequestHeader("x-ncp-sourcecommit-signature-v1") String signature,
              @RequestBody String data
      ) throws NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException, JsonProcessingException {
  
          String secret = "my-secret-key";
  
          Mac mac = Mac.getInstance("HmacSHA256");
          mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
  
          String expectedSignature = Base64.encodeBase64String(mac.doFinal(data.getBytes("UTF-8")));
  
          if(!expectedSignature.equals(signature)){
              System.out.println("this request failed validation");
          }
  
          ObjectMapper mapper = new ObjectMapper();
          Map<String, Object> map = mapper.readValue(data, new TypeReference<Map<String, Object>>() {});
  
          System.out.println("--- received payload ---");
          System.out.println(mapper.writerWithDefaultPrettyPrinter().writeValueAsString(map));
  
          return "test";
      }
  }
  

• Node.js - express

  router.post('/test', (req, res, next) => {
  
    const secret = 'my-secret-key';
  
    const signature = req.get('x-ncp-sourcecommit-signature-v1');
    const data = JSON.stringify(req.body);
  
    const expectedSignature = createHmac('sha256', secret).update(data).digest('base64');
  
    if(expectedSignature !== signature){
      console.log('this request failed validation');
    }
  
    console.log('--- received payload ---');
    console.log(JSON.stringify(req.body, null, 2));
  
    res.send('test');
  });
  

3. 選択したイベントタイプのうち、1つを実行します。
   • 以下の例は、pushイベントの例です。
     
4. ユーザーのウェブサーバコンソールでウェブフック受信ログを確認します。