Configure the PV service webhook

KWS에서 인증 성공 알림 이벤트를 받을 PV 서비스 웹후크를 환경설정하는 방법을 살펴봅니다.

4 분 소요

소개

부모가 부모 인증(Parent Verification, PV) 서비스를 통해 신원 인증에 성공할 경우 키즈 웹 서비스(Kids Web Service, KWS)는 웹후크 호출을 통해 parent-verified 이벤트를 전송하여 시스템에 알립니다.

웹후크를 환경설정하려면 다음과 같은 사항이 필요합니다.

  • KWS가 웹후크를 전송할 URL을 제공해야 합니다.
  • KWS가 부모 인증(Parent Verification) 탭의 제품 통합 세부 정보에서 제공하는 **웹후크 비밀 코드(Webhook secret code)**를 사용하여 시그니처를 생성해야 합니다. 비밀 코드는 웹후크가 KWS에서 전송된 실제 호출인지 확인하기 위해 페이로드에 서명하는 데 사용됩니다.

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

웹후크 URL 구성

  1. 부모 인증(Parent Verification) 탭에서 인증 성공 웹후크 URL 을 입력합니다. KWS는 이 주소로 인증 성공을 확인하는 웹후크를 전송합니다.

중요:

  • 웹후크 URL에 공격자가 조작할 수도 있는 중요한 정보(예시: 손쉽게 반복 적용할 수 있는 숫자 ID)를 포함하지 않도록 합니다.
  • URL에 특수 문자를 포함하지 않습니다.
  1. 퍼블리시하여 테스트(Publish to Test) 를 클릭합니다.

비밀 코드를 사용하여 시그니처 생성

퍼블리시하여 테스트(Publish to Test) 를 클릭하면 부모 인증(Parent Verification) 탭에 웹후크 비밀 코드 가 표시됩니다.

비밀 코드

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

예시

이 예시는 비밀 코드를 사용하여 시그니처를 생성하는 방법을 보여줍니다.

KWS에서 웹후크를 전송합니다. 이 웹후크 호출은 이벤트 전용 페이로드를 래핑하는 공통 구조체를 갖는 HTTPS POST입니다.

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
"name": "webhook-name",
"time": "ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

POST 호출의 헤더는 다음과 같은 구조체를 갖습니다.

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

는 헤더의 타임스탬프 값, 부모 인증 탭의 제품 통합 세부 정보에서 제공하는 웹후크 비밀 코드 및 POST 바디를 사용하여 HMAC_SHA256을 통해 생성됩니다.

const timestamp = /* extracted value of 't=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* secret key, as provided in the Developer Portal */;
const signature = crypto
.createHmac('sha256', secretKey)
.update('${timestamp}.${body}')
.digest('hex');

제품 측면에서는 위 코드와 타임스탬프, 웹후크 비밀 코드 및 POST 바디를 사용하여 동일한 시그니처를 생성해야 합니다. 생성된 시그니처가 웹후크 호출의 헤더에서 전달한 v1 시그니처와 일치하는 경우 해당 웹후크는 직접 전송한 것임을 확인할 수 있습니다.

웹 서버/웹 애플리케이션을 통해 퍼블릭 엔드포인트를 표시합니다. 다른 API 엔드포인트를 빌드하는 방법과 비슷합니다. 이 엔드포인트는 아래에 설명되어 있는 POST 바디를 취하여 시그니처 헤더의 유효성을 검사합니다.

참고: 원본 POST 바디를 사용하는 것이 중요합니다. JSON을 파싱하거나 문자열로 재변환할 경우, JSON 라이브러리 구현이 일치하지 않게 되어 시그니처 또한 일치하지 않게 됩니다.

POST 바디 구조체

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]
Body
{
"name": "webhook-name",
"time": "ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

시그니처

웹후크가 KWS에서 온 것이 맞는지 확인하려면 사용자가 생성한 v1 시그니처와 KWS에서 받은 웹후크 호출 헤더의 v1 시그니처를 비교합니다. 두 시그니처가 일치하는 경우 해당 호출이 KWS에서 온 것임을 확인할 수 있습니다.

시그니처는 비밀 키가 부모 인증 탭에서 제공하는 웹후크 비밀 코드 인 6진법(소문자) HMAC_SHA256 해시입니다.

시그니처는 'x-kws-signature' 헤더에 다음 포맷으로 전송됩니다.

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

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

  • 시그니처 키 회전이 지원되는 경우(시그니처는 변환 기간 동안 이전 키와 현재 키에 전송됨)
  • 알고리즘이 변경되는 경우(v2 시그니처는 변환 기간 동안 v1 시그니처와 함께 전송됨)

v1 시그니처를 생성하는 알고리즘은 마침표(‘.’)와 원본 요청 바디가 그 뒤에 오는 시그니처 헤더에 포함된 타임스탬프의 HMAC_SHA256입니다. 웹후크의 비밀 코드로 HMAC를 초기화합니다.

예시:

const timestamp = /* extracted value of ‘t=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* the webhook secret code from the Parent Verification tab. */;
const signature = crypto
.createHmac('sha256', secretKey)
.update(`${timestamp}.${body}`)
.digest('hex');

참고: 웹후크 URL은 요청 URL이 수정될 수도 있는 경우 reverse-proxies/load-balancers 등의 배후 서비스 내에서 시그니처 유효성 검사를 손쉽게 수행할 수 있게 해주는 시그니처 알고리즘의 일부로 의도적으로 포함되지 않습니다.

웹후크 재시도 행동

웹후크 재시도 행동은 서버에서 POST 요청에 반환한 결과 코드에 따라 다릅니다.

상태 코드행동
200~299호출이 성공적인 것으로 가정됩니다.
0~199, 500 이상, 타임아웃(3초) 또는 네트워크 오류일시적인 실패입니다.호출은 다음과 같은 딜레이 후 익스포넨셜 백오프(exponential backoff)로 재시도됩니다.
  • 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 이상)하면 호출은 실패로 로깅됩니다.

다음 단계

인증 웹뷰에서 지역별로 부모가 사용할 수 있는 인증 방식을 선택합니다.