메인 콘텐츠로 건너뛰기

​
개요

Token ID 만료 웹훅은 사용자가 설정한 Token Expiration 조건에 따라 Token ID가 만료될 때 자동으로 발송됩니다. 이를 통해 토큰의 수명 주기를 추적하고 재사용 문제를 방지할 수 있습니다.
  • Token ID 만료 웹훅은 프로젝트의 Token Expiration 설정이 활성화된 경우에만 발송됩니다.
  • Webhook은 ID Check 프로젝트에 등록된 Webhook URL로 전송됩니다. 웹훅 등록 방법은 여기서 확인해주세요.
  • Webhook의 트리거는 token_expired 입니다.

​
적용 대상

Token ID 만료 웹훅은 다음 두 가지 파이프라인에서 지원됩니다:

ID check

Liveform 기반 신원 확인 메인 파이프라인

FaceAuth

셀피 기반 본인인증 서브 파이프라인
두 파이프라인 모두 Token ID를 사용하므로, Token 만료 시 각각 독립적으로 웹훅이 발송됩니다.
ID check 메인 파이프라인의 Token 만료 웹훅에 대한 자세한 내용은 ID check Token expired 웹훅을 참조하세요.

​
Token ID 종류와 만료 개념

​
사전등록 토큰 (Pre-registered Token)

고객 시스템이 사전에 Token ID를 생성하는 방식입니다.
  • 1회 제출되면 즉시 만료(Expired) 처리됩니다.
  • 명시적인 만료 개념이 존재합니다.

​
비등록 토큰 (Non-registered Token)

토큰 생성 없이 사용하는 방식입니다.
  • 토큰 자체에 명시적 만료가 없습니다.
  • 사용 시점 기준으로 이전 사용 여부 및 유효성을 검증합니다.

​
Token Expiration 설정 조건

웹훅 발송 여부는 프로젝트의 Token Expiration 설정 활성화 여부에 따라 결정됩니다. 다음 두 가지 방식을 지원합니다:
  • Count-based
  • Time-based
사용 횟수 기반으로 토큰 만료를 관리합니다.예: 1회 사용 후 만료

​
웹훅 발송 시점

Token ID가 만료되는 순간, 해당 파이프라인에서 독립적으로 웹훅이 발송됩니다:
  • ID Check 메인 파이프라인: Token ID 만료 시점
  • FaceAuth 서브 파이프라인: Token ID 만료 시점
각 파이프라인에서 독립적으로 만료 이벤트를 감지하므로, 동일한 Token ID라도 파이프라인별로 별도의 웹훅이 발송될 수 있습니다.

​
웹훅 명세

​
파라미터

​
webhook_trigger
string
required
웹훅 이벤트 트리거 (고정값: token_expired)
​
token_id
string
required
만료된 Token ID
​
expired_condition
string
required
설정된 만료 검증 조건
  • count: 사용 횟수 기반 만료
  • time: 시간 기반 만료
​
service
string
required
대상 서비스
  • idCheck: ID Check 메인 파이프라인
  • faceAuth: FaceAuth 서브 파이프라인
​
expired_at
string
만료된 시각 (ISO 8601 형식)
expired_condition이 count인 경우에만 포함됩니다.
​
expected_expired_at
string
만료 예정 시각 (ISO 8601 형식)
expired_condition이 time인 경우에만 포함됩니다.

​
예시

​
Count-based 만료

사용 횟수 기반으로 토큰이 만료된 경우의 웹훅 페이로드:
count-based-example.json
{
  "webhook_trigger": "token_expired",
  "token_id": "tok_abc123def456",
  "expired_condition": "count",
  "expired_at": "2025-11-12T02:23:13.588Z",
  "service": "idCheck"
}
expired_at 필드는 토큰이 실제로 만료된 정확한 시각을 나타냅니다.

​
Time-based 만료

시간 기반으로 토큰이 만료된 경우의 웹훅 페이로드:
time-based-example.json
{
  "webhook_trigger": "token_expired",
  "token_id": "tok_xyz789ghi012",
  "expired_condition": "time",
  "expected_expired_at": "2025-11-12T02:23:13.588Z",
  "service": "faceAuth"
}
expected_expired_at 필드는 토큰이 만료될 예정이었던 시각을 나타냅니다.

​
사용 사례

Token ID 만료 웹훅은 다음과 같은 상황에서 유용합니다:
만료된 토큰을 감지하여 재사용 시도를 차단하고, 보안 이벤트를 기록할 수 있습니다.
토큰의 수명 주기를 추적하여 사용자 플로우를 분석하고, 서비스 품질을 개선할 수 있습니다.
만료 이벤트를 기반으로 새로운 토큰을 자동 생성하거나, 사용자에게 알림을 전송할 수 있습니다.
Token ID 만료 웹훅을 활용하면 토큰 기반 플로우의 보안성과 추적 가능성을 크게 향상시킬 수 있습니다.