웹훅 관리

Classic/VPC 환경에서 이용 가능합니다.

웹훅을 이용하면 SourceCommit 리포지토리에서 발생하는 여러 이벤트에 대한 후처리가 가능합니다. 네이버 클라우드 플랫폼의 Cloud Functions 서비스와 연동하거나 특정 URL을 웹훅에 연결함으로써 원하는 이벤트 데이터를 전달 받아 비즈니스 로직을 처리할 수 있습니다.

아래와 같이 다양한 방식으로 웹훅을 활용할 수 있습니다.

• 코드에 발생하는 변경을 감지하여 SourceBuild, SourceDeploy, SourcePipeline으로의 CI/CD 연계
• Cloud Functions 서비스의 Trigger와 연동하여 Proxy Server에 대한 관리 없이 리포지토리 이벤트에 대한 후처리 로직 수행
• 커밋 푸시 또는 풀 리퀘스트 생성 알림을 통해 코드 리뷰 시간 단축
• FileSafer 악성 코드 검사 결과를 즉각적으로 수신
• LFS를 통한 File 잠금/잠금 해제 여부를 즉각적으로 수신

웹훅 관리

웹훅을 이용하려면 먼저 웹훅이 호출되었을 때 이벤트를 전달할 연결 대상을 지정하여 웹훅을 생성해야 합니다.

웹훅 생성

웹훅을 생성하는 방법은 다음과 같습니다.

1. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
2. Services > Developer Tools > SourceCommit 메뉴를 차례대로 클릭해 주십시오.
3. SourceCommit 화면에서 리포지토리를 선택한 후 [코드로 이동] 버튼을 클릭해 주십시오.
   • 리포지토리 목록에서 리포지토리 이름을 클릭해도 됩니다.
4. 리포지토리 상세 기능 화면에서 [Hooks] 탭을 클릭해 주십시오.
   
5. [생성] 버튼을 클릭해 주십시오.
   
6. 생성할 웹훅 이름과 설명을 입력해 주십시오.
   • 웹훅 이름은 알파벳, 숫자, 특수 문자(-, _)를 사용하여 50자 내로 입력 가능하며, 이미 생성된 웹훅과 동일한 이름 입력 불가
   • 설명은 300자 이내 입력 가능
7. 웹훅이 호출 될 이벤트 유형을 선택해 주십시오.
   • 웹훅이 속한 리포지토리 내에서 해당 이벤트가 발생하면 웹훅이 호출됩니다.
   • 이벤트 유형에 대한 자세한 설명은 웹훅 이벤트 목록을 참고해주십시오.
8. 웹훅에 연결할 대상을 추가해주십시오. 이벤트가 발생하여 웹훅이 호출되면 연결 대상을 통해 데이터를 전달합니다.
   대상 유형에 따라 대상을 추가하는 방법이 다릅니다. 아래 가이드를 참고해주십시오.
   • 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. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
2. Services > Developer Tools > SourceCommit 메뉴를 차례대로 클릭해 주십시오.
3. SourceCommit 화면에서 리포지토리를 선택한 후 [코드로 이동] 버튼을 클릭해 주십시오.
   • 리포지토리 목록에서 리포지토리 이름을 클릭해도 됩니다.
4. 리포지토리 상세 기능 화면에서 [Hooks] 탭을 클릭해 주십시오.
5. [수정] 버튼을 클릭해 주십시오.
6. 웹훅 설정을 변경한 후 [적용] 버튼을 클릭해 주십시오.
   • 웹훅 설정 시 입력하는 내용에 관한 자세한 내용은 웹훅 생성을 참고해 주십시오.

웹훅 삭제

웹훅 호출을 더 이상 원하지 않는 경우 웹훅을 삭제할 수 있습니다.
웹훅을 삭제하는 방법은 다음과 같습니다.

1. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
2. Services > Developer Tools > SourceCommit 메뉴를 차례대로 클릭해 주십시오.
3. SourceCommit 화면에서 리포지토리를 선택한 후 [코드로 이동] 버튼을 클릭해 주십시오.
   • 리포지토리 목록에서 리포지토리 이름을 클릭해도 됩니다.
4. 리포지토리 상세 기능 화면에서 [Hooks] 탭을 클릭해 주십시오.
5. 보유중인 웹훅 목록에서 삭제할 웹훅을 선택하고 [삭제] 버튼을 클릭해 주십시오.
6. 삭제 확인 창에서 최종적으로 [삭제] 버튼을 클릭해 주십시오.

웹훅 호출 결과 확인

웹훅 연결 대상 별로 호출 결과를 확인할 수 있습니다.

• Cloud Functions 연결 대상 호출 결과 확인
• URL 연결 대상 호출 결과 확인

Cloud Functions 연결 대상 호출 결과 확인

연결 대상이 Cloud Functions인 웹훅은 Cloud Functions 서비스 콘솔에서 호출 결과를 확인할 수 있습니다.

1. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
2. Services > Developer Tools > SourceCommit 메뉴를 차례대로 클릭해 주십시오.
3. SourceCommit 화면에서 리포지토리를 선택한 후 [코드로 이동] 버튼을 클릭해 주십시오.
   • 리포지토리 목록에서 리포지토리 이름을 클릭해도 됩니다.
4. 리포지토리 상세 기능 화면에서 [Hooks] 탭을 클릭해 주십시오.
5. 확인하고자 하는 웹훅의 [대상 정보] 컬럼 내 트리거 이름을 클릭하여 Cloud Function 서비스 콘솔로 이동해주십시오.
   
   • 트리거 호출 결과에 대한 자세한 내용은 트리거 모니터링 가이드를 참고해 주십시오.

URL 연결 대상 호출 결과 확인

연결 대상이 URL인 웹훅은 웹훅 목록 화면에서 [호출 결과] 버튼을 클릭하여 확인할 수 있습니다.

1. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오.
2. Services > Developer Tools > SourceCommit 메뉴를 차례대로 클릭해 주십시오.
3. SourceCommit 화면에서 리포지토리를 선택한 후 [코드로 이동] 버튼을 클릭해 주십시오.
   • 리포지토리 목록에서 리포지토리 이름을 클릭해도 됩니다.
4. 리포지토리 상세 기능 화면에서 [Hooks] 탭을 클릭해 주십시오.
5. 호출 결과를 확인할 URL 유형의 웹훅을 선택한 후 [호출 결과] 버튼을 클릭해 주십시오.
   
   • 대상 유형: 웹훅 대상 유형 (현재 URL만 지원)
   • 엔드포인트: 웹훅 대상 URL
   • 호출 시간: 웹훅 호출 시간
   • 상태: 호출 성공, 실패 여부
6. 상세 호출 결과를 확인하려면 [보기] 버튼을 클릭해주십시오.
   
   • 요청 정보
     • 요청 헤더: 웹훅 호출 시 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. 선택한 이벤트 유형 중 하나를 실행시켜 주십시오.
   • 아래 예시는 push 이벤트에 대한 예시입니다.
     
4. 사용자 웹서버 콘솔에서 웹훅 수신 로그를 확인해 주십시오.