부모 인증 서비스 웹후크 구성

KWS에서 인증 성공 이벤트를 받는 부모 인증 서비스 웹후크를 구성하는 방법입니다.

4 분 소요

소개

부모가 부모 인증 서비스를 사용하여 신원을 성공적으로 인증하면 KWS에서 웹후크 호출을 통해 parent-verified 이벤트를 전송하여 시스템에 알립니다.

개발자 쪽에서 웹후크를 구성하려면 다음과 같이 진행해야 합니다.

참고: 테스트 환경과 프로덕션 환경은 각각 고유한 웹후크 암호 코드와 함께 제공됩니다.

웹후크 URL 설정

  1. 부모 인증(Parent Verification) 탭에서 성공적인 인증 웹후크 URL(Successful verification webhook URL) 을 입력합니다. KWS는 여기에서 성공적인 인증을 확인하는 웹후크를 전송합니다.

    중요:

    • 웹후크 URL에는 공격자의 조작에 민감한 정보를 포함하지 마세요(예: 쉽게 반복할 수 있는 숫자로 된 ID).
    • URL에는 특수 문자를 포함하지 마세요.

  2. 테스트로 게시(Publish to Test) 를 클릭합니다.

암호 코드를 사용하여 시그니처 생성

부모 인증(Parent Verification) 탭에서 테스트로 게시(Publish to Test) 를 클릭하면 웹후크 암호 코드(Webhook secret code) 가 표시됩니다.

암호 코드

이미지를 클릭하면 최대 크기로 볼 수 있습니다.

예시

이 예시에서는 암호 코드를 사용하여 시그니처를 생성하는 방법을 보여줍니다.

KWS에서 웹후크를 전송합니다. 웹후크 호출은 이벤트별 페이로드를 정리하는 공통 구조를 갖춘 HTTP POST입니다.

POST 호출의 헤더는 다음과 같은 구조로 되어 있습니다.

<시그니처>는 헤더의 타임스탬프 값을 사용하여 HMAC_SHA256을 통해 생성되고, 웹후크 암호 코드(Webhook secret code) 는 부모 인증(Parent Verification) 탭과 POST 본문의 통합 세부 정보에 표시됩니다.

제품 측에서 위의 코드와 타임스탬프, 웹후크 암호 코드(Webhook secret code) 와 POST 본문을 사용하여 동일한 시그니처를 생성해야 합니다. 생성한 시그니처가 웹후크 호출의 헤더에서 전달한 v1 시그니처와 일치하면 KWS에서 전송한 웹후크임을 확인할 수 있습니다.

(다른 API 엔드포인트를 빌드한 방법과 유사하게) 웹 서버/웹 애플리케이션을 통해 공개 엔드포인트를 표면화합니다. 이 엔드포인트는 아래에서 설명한 POST 본문을 가지고 시그니처 헤더의 유효성을 검사합니다.

참고: 원시 POST 본문을 사용하는 것이 중요합니다. 일관되지 않은 JSON 라이브러리 구현으로 인해 일치하지 않는 시그니처가 발생할 수 있으므로, JSON을 파싱하거나 다시 스트링화하지 마십시오.

POST 본문 구조

시그니처

KWS에서 보내는 웹후크가 맞는지 확인하기 위해 생성한 v1 시그니처를 KWS에서 받는 웹후크 콜의 헤더에 있는 v1 시그니처와 비교하세요. 시그니처가 일치하면 해당 호출을 KWS에서 전송했음을 확인할 수 있습니다.

시그니처는 16진수(소문자) 형식의 HMAC_SHA256 해시입니다. 여기에서 비밀 키는 부모 인증(Parent Verification) 탭에서 제공하는 웹후크 암호 코드(Webhook secret code) 입니다.

시그니처는 다음과 같은 형식으로 x-kws-signature 헤더에서 전송됩니다.

참고: 현재는 하나의 v1 시그니처만 포함되지만, 다음과 같은 경우에는 헤더에 여러 시그니처가 포함될 수 있습니다.

  • 시그니처 키 로테이션이 지원됩니다. 시그니처는 트랜지션 기간 동안 이전 및 현재 키에 대해 전송됩니다.
  • 시그니처 알고리즘이 변경됩니다. v2 시그니처는 트랜지션 기간 동안 v1 시그니처와 함께 전송됩니다.

v1 시그니처를 생성하는 알고리즘은 시그니처 헤더에 포함된 타임스탬프의 HMAC_SHA256이며, 다음에 마침표('.'), 그다음에는 원시 요청 본문이 이어집니다. 웹후크의 암호 코드로 HMAC을 초기화합니다.

예를 들면

참고: 요청 URL이 수정될 수 있는 경우, 웹후크 URL은 리버스 프록시/로드 밸런서 이후의 서비스 내에서 보다 쉬운 시그니처 검증을 허용하는 시그니처 알고리즘에서 의도적으로 제외됩니다.

웹후크 재시도 행동

웹후크 재시도 행동은 서버가 POST 요청에 반환하는 상태 코드에 따라 다릅니다.

상태 코드행동
200~299호출이 성공적인 것으로 간주됩니다.
0~199, 500 이상, 타임아웃(3초) 또는 네트워크 오류일시적 오류입니다. 다음 딜레이 후 지수 백오프로 호출을 재시도할 수 있습니다.
  • 30초
  • 1분(총 1.5분)
  • 2분(총 3.5분)
  • 4분(총 7.5분)
  • 8분(총 15.5분)
  • 16분(총 31.5분)
  • 32분(총 1시간 3.5분)
  • 1시간 4분(총 2시간 7.5분)
  • 2시간 8분(총 4시간 15.5분)
  • 4시간 16분(총 8분 31.5분)
  • 8시간 32분(총 17시간 3.5분)
  • 17시간 4분(총 34시간 7.5분)
400+마지막 재시도가 실패했습니다. 호출이 실패된 것으로 기록됩니다.

최종 재시도가 실패하면(상태 코드 400 이상) 호출이 실패한 것으로 로깅됩니다.

다음 단계

부모가 사용할 수 있도록 제공할 (지역에 따라 다른) 인증 방법을 선택합니다.