웹훅

웹훅을 사용하면 데이터를 사용할 수 있는지 확인하기 위해 API를 폴링하는 대신 k-ID Engine에서 발생하는 이벤트를 실시간으로 구독할 수 있습니다.

웹훅이란 무엇인가요?

웹훅은 다음과 같은 다양한 목적으로 사용할 수 있습니다:

1. Challenge 완료 결과 처리
2. 연령 확인 결과 처리
3. k-ID 세션 변경 처리

웹훅 설정

웹훅은 Compliance Studio에서 이벤트가 발생할 때 k-ID Engine이 호출하는 URL을 지정하여 구성됩니다. URL은 보안 HTTPS URL이어야 합니다. k-ID Engine은 이벤트 데이터를 포함하는 JSON 페이로드와 함께 URL에 POST 요청을 보냅니다.

정보

웹훅은 개별 제품과 연결됩니다. 둘 이상의 k-ID 제품이 있는 경우 모든 제품에 대해 동일한 엔드포인트를 사용할 수 있지만, API 호출(예: /session/get)을 수행하려면 올바른 제품별 k-ID API 키를 검색해야 합니다.

웹훅은 Compliance Studio의 제품 개발자 설정 섹션에서 구성할 수 있습니다.

웹훅 이벤트 구조

웹훅 URL로 전송되는 JSON 페이로드에는 다음 필드가 포함됩니다:

• eventType - 발생한 이벤트 유형
• data - 이벤트와 관련된 데이터

이벤트 유형과 함께 X-Event-Type 헤더도 전송됩니다.

웹훅 요청 검증

웹훅은 공용 인터넷을 통해 전송되므로 요청이 k-ID에서 오는지 확인하는 것이 중요합니다. 구성된 웹훅 시크릿을 사용하여 이벤트 페이로드 서명을 확인하여 수행됩니다.

모든 요청에는 다음 헤더가 포함됩니다:

• X-Signature-Timestamp - 요청의 타임스탬프(UNIX epoch 초)
• X-Signature-Hmac-Sha256 - UTF-8로 인코딩된 타임스탬프와 요청 본문을 연결한 HMAC SHA-256 키 해시로, 웹훅 시크릿을 키로 사용하고 소문자 16진수 문자열로 인코딩됩니다

서명이 유효하지 않으면 요청은 401 상태 코드로 거부되어야 합니다. 검증된 서명이 있는 웹훅 요청은 처리되고 200 상태 코드로 수락할 수 있습니다.

검증 코드 예시

const crypto = require("crypto");

// [Compliance Studio](/compliance-studio/products/creating-new-product)에서 구성한 웹훅 시크릿
const SECRET = "your-secret";

const timestamp = req.get("X-Signature-Timestamp");
const signature = req.get("X-Signature-Hmac-Sha256");
const body = req.rawBody; // 원시 요청 본문(문자열)

// 예상 서명 계산
const hmac = crypto.createHmac("sha256", SECRET);
hmac.update(timestamp + body);
const expectedSignature = hmac.digest("hex");

// 서명을 안전하게 비교
if (
  !crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  )
) {
  return res.status(401).end("Unauthorized");
}

이벤트 유형

이벤트 유형	설명
Challenge.StateChange	부모 동의 Challenge가 상태를 변경할 때 발생
Verification.Result	확인 시도의 결과와 함께 발생
Account.Delete	계정이 삭제될 때 발생
AgeAssurance.Result	Age Assurance 평가 결과와 함께 발생 (더 이상 사용되지 않음, Verification.Result로 대체됨)
ParentalConsent.Granted	부모 동의가 부여될 때 발생
Session.ChangePermissions	부모가 세션 권한을 수정할 때 발생
Session.Delete	세션이 삭제될 때 발생
Test	웹훅이 올바르게 작동하는지 확인하는 데 사용