메인 콘텐츠로 건너뛰기
  • Token ID 만료 웹훅은 프로젝트의 Token Expiration 설정이 활성화된 경우에만 발송됩니다.
  • 토큰 만료는 사용 횟수 기반(count-based) 또는 시간 기반(time-based)으로 설정할 수 있습니다.

​
Token ID 종류와 만료 개념

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

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

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

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

​
Token Expiration 설정 조건

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

​
웹훅 예시

{
  "webhook_trigger": "token_expired",
  "token_id": "tok_abc123def456",
  "expired_condition": "count",
  "expired_at": "2025-11-12T02:23:13.588Z",
  "service": "idCheck"
}

​
응답 필드

​
webhook_trigger
string
웹훅 트리거 유형 - token_expired는 Token ID가 만료되었음을 의미
​
token_id
string
만료된 Token ID
​
expired_condition
string
설정된 만료 검증 조건
  • count: 사용 횟수 기반 만료
  • time: 시간 기반 만료
​
service
string
대상 서비스 - idCheck (ID check 메인 파이프라인)
​
expired_at
string
만료된 시각 (ISO 8601 형식)
expired_condition이 count인 경우에만 포함됩니다. 토큰이 실제로 만료된 정확한 시각을 나타냅니다.
​
expected_expired_at
string
만료 예정 시각 (ISO 8601 형식)
expired_condition이 time인 경우에만 포함됩니다. 토큰이 만료될 예정이었던 시각을 나타냅니다.

​
사용 사례

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