웹훅 개요
웹훅은 Challenge 상태 변경 및 확인 결과와 같은 k-ID의 중요한 이벤트에 대해 서버에 알립니다. 각 제품에 대해 Compliance Studio의 개발자 설정에서 웹훅 URL 및 비밀을 구성하세요.
페이로드에는 eventType과 data 객체가 포함됩니다. 페이로드 스키마는 이벤트 유형을 참조하세요.
이벤트 유형
| 이벤트 유형 | 설명 |
|---|---|
Challenge.StateChange | 부모 동의 Challenge가 상태를 변경할 때 발생 |
Verification.Result | 확인 시도 결과와 함께 발생 |
Verification.Revoke | 이전에 통과한 인증이 취소되었을 때 발생 |
Account.Delete | 계정이 삭제될 때 발생 |
AgeAssurance.Result | 연령 보증 평가 결과와 함께 발생(더 이상 사용되지 않음, Verification.Result로 대체됨) |
ParentalConsent.Granted | 부모 동의가 부여될 때 발생 |
Session.ChangePermissions | 부모가 세션 권한을 수정할 때 발생 |
Session.Delete | 세션이 삭제될 때 발생 |
Test | 웹훅이 올바르게 작동하는지 확인하는 데 사용 |
서명 검증
구성된 웹훅 비밀을 사용하여 웹훅 요청을 검증하세요.
헤더
각 요청과 함께 전송되는 헤더:
X-Signature-Timestamp: UNIX epoch 초X-Signature-Hmac-Sha256: (타임스탬프 + 원시 본문)의 HMAC SHA-256, 웹훅 비밀을 키로 사용, 16진수 인코딩(소문자)
예상 동작
- 유효한 서명에 대해
200반환 - 잘못된 서명에 대해
401반환
구현 세부 사항은 웹훅 요청 검증을 참조하세요.
전달, 재시도 및 복구
전달 보장
k-ID는 최소 1회(at-least-once) 보장으로 웹훅 이벤트를 전달합니다. 엔드포인트는 동일한 이벤트를 두 번 이상 수신할 수 있으므로 핸들러를 멱등하게 설계하세요. data.id 필드(확인 또는 Challenge ID)를 사용하여 이미 처리한 이벤트의 중복을 제거하세요.
재시도 정책
엔드포인트가 200이 아닌 상태 코드를 반환하거나 요청이 시간 초과되면 k-ID는 2회 재시도합니다:
| 시도 | 이전 시도 후 지연 |
|---|---|
| 1차 재시도 | 5초 |
| 2차 재시도 | 10초 |
초기 시도와 2회 재시도(총 3회 시도) 후 k-ID는 해당 이벤트의 전달을 중단합니다.
누락된 웹훅 처리
서버가 다운되었거나 웹훅이 성공적으로 전달되지 않은 경우, 플로우를 시작할 때 저장한 ID를 사용하여 서버에서 관련 상태 엔드포인트를 폴링하여 복구하세요:
- 확인: 확인 ID로
GET /age-verification/get-status호출 - Challenge: Challenge ID로
GET /challenge/get-status호출
플로우를 시작할 때 수신하는 확인 또는 Challenge ID를 항상 저장하세요. 웹훅 핸들러가 예상 시간 내에 결과를 수신하지 못하면 해당 get-status 엔드포인트를 호출하여 현재 상태를 조회하세요. 이 리디렉션→폴링 패턴을 사용하면 모든 웹훅 전달이 실패하더라도 결과를 놓치지 않습니다.
멱등성
웹훅 이벤트는 멱등합니다. 동일한 이벤트가 두 번 이상 전달될 수 있습니다. 예를 들어 네트워크 문제로 전달 상태가 불명확해진 경우입니다. 이벤트에 대해 작업을 수행하기 전에 해당 이벤트가 이미 처리되었는지 항상 확인하세요. 간단한 방법은 처리된 이벤트 ID(data.id 필드)를 추적하고 중복을 건너뛰는 것입니다.