Webフックの管理

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

Webフックを利用すると、SourceCommitリポジトリで発生する複数のイベントの後処理が可能です。NAVERクラウドプラットフォームの Cloud Functionsサービスと連携したり、特定 URLを Webフックに接続することで、希望するイベントデータを受け取り、ビジネスロジックを処理することができます。

以下のように様々な方法で Webフックを活用することができます。

• コードに発生する変更を感知し、SourceBuild、SourceDeploy、SourcePipelineへの CI/CD連携
• Cloud Functionsサービスの Triggerと連携して Proxy Serverに対する管理なしにリポジトリイベントへの後処理ロジックを実行
• コミットプッシュまたはプルリクエスト生成通知によりコードレビュー時間を短縮
• FileSafer悪性コード検査結果を即座に受信
• LFSによる Fileロック/ロック解除の可否を即座に受信

Webフックの管理

Webフックを利用するには、まず Webフックが呼び出されたときにイベントを配信する接続対象を指定して Webフックを作成する必要があります。

Webフック作成

Webフックを作成する方法は以下のとおりです。

1. NAVERクラウドプラットフォームコンソールにアクセスします。
2. Services > Developer Tools > SourceCommitメニューを順番にクリックしてください。
3. SourceCommit画面でリポジトリを選択し、[コードに移動] ボタンをクリックします。
   • リポジトリリストでリポジトリ名をクリックしても構いません。
4. リポジトリの詳細機能画面で [Hooks] タブをクリックします。
   
5. [作成] ボタンをクリックします。
   
6. 作成する Webフック名と説明を入力します。
   • Webフック名はアルファベット、数字、特殊文字(-,_)を使用し50文字以内で入力可能で、既存の Webフックと同じ名前は入力不可
   • 説明は300文字以内を入力可能
7. Webフックが呼び出されるイベントタイプを選択してください。
   • Webフックが属するリポジトリ内でそのイベントが発生すると、Webフックが呼び出されます。
   • イベントタイプについての詳細は、Webフックイベントリストをご参照ください。
8. Webフックに接続する対象を追加してください。イベントが発生して Webフックが呼び出されると、接続対象を介してデータを配信します。
   対象タイプによって対象の追加方法が異なります。以下のガイドを参考にしてください。
   • Cloud Functions接続対象の追加
   • URL接続対象の追加

Cloud Functions接続対象の追加

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

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 (選択)
     • Webフック呼び出しが SourceCommitサービスから呼び出されたものであることを保障し、データが途中で偽造変造されることを防止するため。
     • Webフック呼び出し時に request bodyを Secret keyへ Hmac SHA256 暗号化した値が 「x-ncp-sourcecommit-signature-v1」 へッダを介して送信される(例)
     • 200文字以内で入力可能

3. URLを有効にするかどうかを決定し、[追加] ボタンをクリックして URLを作成してください。

   • リポジトリ内のイベントが発生して Webフックが呼び出されると、選択した URLの中で有効かどうかが ONになっている URLでのみデータが送信されます。

4. Webフック作成の [作成] ボタンをクリックして、Webフックを作成してください。

Webフック設定の変更

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

Webフック設定を変更する方法は以下のとおりです。

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

Webフックの削除

Webフックの呼び出しをこれ以上希望しない場合は、Webフックを削除できます。Webフックを削除する方法は以下のとおりです。

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

Webフックの呼び出し結果を確認

Webフック接続先ごとに呼び出し結果を確認できます。

• Cloud Functions接続対象の呼び出し結果の確認
• URL接続対象の呼び出し結果の確認

Cloud Functions接続対象の呼び出し結果の確認

接続対象が Cloud Functionsである Webフックは、Cloud Functionsサービスコンソールで呼び出し結果を確認できます。

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

URL接続対象の呼び出し結果の確認

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

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

URL対象 Webフックデータ受信

URL対象 Webフックデータを受信した後、secret値と'x-ncp-sourcecommit-signature-v1'ヘッダを利用して偽造変造の有無を検証し、出力する例を紹介します。

1. Webフックの作成および URL接続対象の追加を参考にして、以下の内容で Webフックを作成してください。
   

   参考

   • URL Webフックデータ転送時の HTTP Methodは POSTです。
   • Webフック呼び出し時に requestbodyを Secretkeyに Hmac SHA256暗号化した値が 'x-ncp-sourcecommit-signature-v1' ヘッダを介して送信されます。
   • Secret値が空白の場合、'x-ncp-sourcecommit-signature-v1' ヘッダは提供されません。

2. ユーザーのウェブサーバから Webフックデータを受信できるように準備してください。

   注意

   • 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. 選択したイベントタイプのいずれかを実行してください。
   • 以下の例は、pushイベントの例です。
     
4. ユーザーのウェブサーバコンソールで Webフック受信ログを確認してください。