웹훅

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

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

1. 도전 완료 결과 처리
2. 나이 확인 결과 처리
3. k-ID 세션의 변경사항 처리

웹훅 설정

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

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

웹훅은 선택된 제품의 개발자 설정에서 구성할 수 있습니다. /products/[productId]/developer에서 이 페이지에 액세스할 수 있습니다.

웹훅 구성 페이지

개발자 설정의 웹훅 섹션을 통해 특정 이벤트가 발생할 때 k-ID가 호출할 HTTPS URL을 구성할 수 있습니다. 애플리케이션에 대한 원하는 웹훅 URL을 입력하고 저장을 클릭하면 시스템에서 구성이 업데이트됩니다. 변경사항은 현재 설정에 따라 테스트 모드 또는 라이브 모드의 적절한 환경에 자동으로 적용됩니다.

이를 통해 테스트 중이든 프로덕션에서 운영 중이든 이벤트 알림이 애플리케이션으로 올바르고 안전하게 라우팅됩니다.

참고: 저장 버튼은 테스트로 푸시 및 라이브 게시 버튼과 다릅니다. 웹훅을 저장하고 업데이트하는 것은 사용자에게 직접적인 영향을 주지 않지만, 테스트로 푸시 또는 라이브 게시를 사용하여 만든 변경사항은 전체 사용자 경험에 영향을 줄 수 있으며 효과를 발휘하기 전에 k-ID 팀의 검토가 필요할 수 있습니다.

또한 웹훅 테스트 버튼 이 있어 시크릿 유무에 관계없이 엔드포인트가 올바르게 설정되었는지 확인할 수 있습니다. 시크릿이 구성된 경우, 이 버튼을 클릭하면 웹훅 엔드포인트로 두 개의 요청이 전송됩니다: 하나는 유효한 서명으로, 다른 하나는 무효한 서명으로 전송됩니다. 테스트는 유효한 서명 요청에 대해 200 OK를, 무효한 서명 요청에 대해 401 Unauthorized를 반환할 때에만 통과합니다. 웹훅 요청 검증에 대한 자세한 내용은 문서에서 찾을 수 있습니다. 이 버튼은 테스트 이벤트를 시뮬레이션하며, 문서의 테스트 이벤트 섹션에서 참조할 수 있습니다.

웹훅 이벤트 구조

웹훅 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");

// 개발자 포털에서 구성한 웹훅 시크릿
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");
}

웹훅 이벤트 유형

다음 이벤트 유형을 사용할 수 있습니다:

• Test
• Challenge.StateChange
• Session.ChangePermissions
• Session.Delete
• Verification.Result
• AgeAssurance.Result

Test

이 이벤트 유형은 웹훅이 올바르게 작동하는지 확인하는 데 사용됩니다. 웹훅 수신기에 의해 처리되어야 합니다.

예시 페이로드:

{
  "eventType": "Test",
  "data": {
    "id": "12345678-1234-1234-1234-123456789abc"
  }
}

Challenge State Change

속성:

• id - 도전 ID
• productId - 제품 ID
• status - PASS, FAIL, 또는 IN_PROGRESS일 수 있습니다
• sessionId (선택사항) - 상태가 PASS인 경우 세션 ID
• approverEmail (선택사항) - 상태가 PASS인 경우 승인자의 이메일
• kuid (선택사항) - 상태가 pass인 경우 k-ID 사용자 ID

예시 페이로드:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "683409f1-2930-4132-89ad-827462eed9af",
    "productId": 42,
    "status": "PASS",
    "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
    "approverEmail": "user@example.com",
    "kuid": "123456"
  }
}

Session Change Permissions

세션 권한 변경의 경우, 이 유형의 이벤트는 권한이 k-ID 가족 포털에서 부모에 의해 직접 수정될 때만 웹훅 수신기로 전송됩니다. 플레이어가 다른 나이 카테고리에 속하게 되거나 관할권에서 더 많은 기능에 액세스할 수 있게 하는 나이 임계값을 넘는 생일을 맞이한 경우, 게임은 /session/get API를 호출하여 세션에 대한 변경된 권한을 받아야 합니다.

속성:

• id - 세션 ID
• productId - 제품 ID

예시 페이로드:

{
  "eventType": "Session.ChangePermissions",
  "data": {
    "id": "78c299b2-5c33-4bde-84fe-8fc950fc7a96",
    "productId": 42
  }
}

Session Delete

속성:

• id - 세션 ID
• productId - 제품 ID

예시 페이로드:

{
  "eventType": "Session.Delete",
  "data": {
    "id": "2d064cf7-0726-4193-b19a-8bd387937e60",
    "productId": 42
  }
}

Verification Result

속성:

• id - 고유 확인 ID
• status - PASS 또는 FAIL일 수 있습니다
• ageCategory (선택사항) - 추정된 나이 카테고리. adult, digital-youth, 또는 digital-minor일 수 있습니다. status가 PASS인 경우에만 설정됩니다
• method (선택사항) - 사용된 확인 방법. id-document, credit-card, 또는 age-estimation일 수 있습니다. status가 PASS인 경우에만 설정됩니다
• failureReason (선택사항) - 확인이 실패한 이유. age-criteria-not-met, max-attempts-exceeded, 또는 fraudulent-activity-detected일 수 있습니다. status가 FAIL인 경우에만 설정됩니다
• age (선택사항) - 나이 세부사항. status가 PASS이고 확인 시나리오가 나이를 반환하도록 구성된 경우에만 설정됩니다

age 속성:

• low - 추정된 나이의 하한. 신분증 문서 확인과 같은 하드 나이 확인 방법의 경우, 이는 정확한 나이가 됩니다
• high - 추정된 나이의 상한. 신분증 문서 확인과 같은 하드 나이 확인 방법의 경우, 이는 정확한 나이가 됩니다

예시 페이로드:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

Age Assurance Result

속성:

• id - 고유 확인 ID
• status - PASS 또는 FAIL일 수 있습니다
• ageRange (선택사항) - 추정된 나이 범위에 대한 세부사항

ageRange 속성:

• minAge - 추정된 최소 나이
• maxAge - 추정된 최대 나이

예시 페이로드:

{
  "eventType": "AgeAssurance.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageRange": {
      "minAge": 18,
      "maxAge": 25
    }
  }
}