> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token ID 만료 웹훅

> Token ID가 만료될 때 발송되는 웹훅 이벤트 가이드

## 개요

Token ID 만료 웹훅은 사용자가 설정한 Token Expiration 조건에 따라 Token ID가 만료될 때 자동으로 발송됩니다. 이를 통해 토큰의 수명 주기를 추적하고 재사용 문제를 방지할 수 있습니다.

<Note>
  * Token ID 만료 웹훅은 프로젝트의 Token Expiration 설정이 활성화된 경우에만 발송됩니다.
  * Webhook은 ID Check 프로젝트에 등록된 Webhook URL로 전송됩니다. 웹훅 등록 방법은 [여기서](/ko/idcheck/webhooks/overview#2-register-webhook-events) 확인해주세요.
  * Webhook의 트리거는 `token_expired` 입니다.
</Note>

## 적용 대상

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

<CardGroup cols={2}>
  <Card title="ID check" icon="id-card" href="/ko/idcheck/webhooks/idcheck-token">
    Liveform 기반 신원 확인 메인 파이프라인
  </Card>

  <Card title="FaceAuth" icon="face-smile">
    셀피 기반 본인인증 서브 파이프라인
  </Card>
</CardGroup>

두 파이프라인 모두 Token ID를 사용하므로, Token 만료 시 각각 독립적으로 웹훅이 발송됩니다.

<Info>
  ID check 메인 파이프라인의 Token 만료 웹훅에 대한 자세한 내용은 [ID check Token expired 웹훅](/ko/idcheck/webhooks/idcheck-token)을 참조하세요.
</Info>

## Token ID 종류와 만료 개념

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

고객 시스템이 사전에 Token ID를 생성하는 방식입니다.

<Info>
  * 1회 제출되면 즉시 만료(Expired) 처리됩니다.
  * 명시적인 만료 개념이 존재합니다.
</Info>

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

토큰 생성 없이 사용하는 방식입니다.

<Info>
  * 토큰 자체에 명시적 만료가 없습니다.
  * 사용 시점 기준으로 이전 사용 여부 및 유효성을 검증합니다.
</Info>

## Token Expiration 설정 조건

웹훅 발송 여부는 프로젝트의 Token Expiration 설정 활성화 여부에 따라 결정됩니다. 다음 두 가지 방식을 지원합니다:

<Tabs>
  <Tab title="Count-based">
    사용 횟수 기반으로 토큰 만료를 관리합니다.

    예: 1회 사용 후 만료
  </Tab>

  <Tab title="Time-based">
    시간 기반으로 토큰 만료를 관리합니다.

    예: 24시간 이후 만료
  </Tab>
</Tabs>

## 웹훅 발송 시점

Token ID가 만료되는 순간, 해당 파이프라인에서 독립적으로 웹훅이 발송됩니다:

* **ID Check 메인 파이프라인**: Token ID 만료 시점
* **FaceAuth 서브 파이프라인**: Token ID 만료 시점

<Warning>
  각 파이프라인에서 독립적으로 만료 이벤트를 감지하므로, 동일한 Token ID라도 파이프라인별로 별도의 웹훅이 발송될 수 있습니다.
</Warning>

## 웹훅 명세

### 파라미터

<ResponseField name="webhook_trigger" type="string" required>
  웹훅 이벤트 트리거 (고정값: `token_expired`)
</ResponseField>

<ResponseField name="token_id" type="string" required>
  만료된 Token ID
</ResponseField>

<ResponseField name="expired_condition" type="string" required>
  설정된 만료 검증 조건

  * `count`: 사용 횟수 기반 만료
  * `time`: 시간 기반 만료
</ResponseField>

<ResponseField name="service" type="string" required>
  대상 서비스

  * `idCheck`: ID Check 메인 파이프라인
  * `faceAuth`: FaceAuth 서브 파이프라인
</ResponseField>

<ResponseField name="expired_at" type="string">
  만료된 시각 (ISO 8601 형식)

  <Info>
    `expired_condition`이 `count`인 경우에만 포함됩니다.
  </Info>
</ResponseField>

<ResponseField name="expected_expired_at" type="string">
  만료 예정 시각 (ISO 8601 형식)

  <Info>
    `expired_condition`이 `time`인 경우에만 포함됩니다.
  </Info>
</ResponseField>

## 예시

### Count-based 만료

사용 횟수 기반으로 토큰이 만료된 경우의 웹훅 페이로드:

```json count-based-example.json theme={null}
{
  "webhook_trigger": "token_expired",
  "token_id": "tok_abc123def456",
  "expired_condition": "count",
  "expired_at": "2025-11-12T02:23:13.588Z",
  "service": "idCheck"
}
```

<Check>
  `expired_at` 필드는 토큰이 실제로 만료된 정확한 시각을 나타냅니다.
</Check>

### Time-based 만료

시간 기반으로 토큰이 만료된 경우의 웹훅 페이로드:

```json time-based-example.json theme={null}
{
  "webhook_trigger": "token_expired",
  "token_id": "tok_xyz789ghi012",
  "expired_condition": "time",
  "expected_expired_at": "2025-11-12T02:23:13.588Z",
  "service": "faceAuth"
}
```

<Check>
  `expected_expired_at` 필드는 토큰이 만료될 예정이었던 시각을 나타냅니다.
</Check>

## 사용 사례

Token ID 만료 웹훅은 다음과 같은 상황에서 유용합니다:

<AccordionGroup>
  <Accordion title="토큰 재사용 방지">
    만료된 토큰을 감지하여 재사용 시도를 차단하고, 보안 이벤트를 기록할 수 있습니다.
  </Accordion>

  <Accordion title="서비스 로직 추적">
    토큰의 수명 주기를 추적하여 사용자 플로우를 분석하고, 서비스 품질을 개선할 수 있습니다.
  </Accordion>

  <Accordion title="자동화된 토큰 관리">
    만료 이벤트를 기반으로 새로운 토큰을 자동 생성하거나, 사용자에게 알림을 전송할 수 있습니다.
  </Accordion>
</AccordionGroup>

<Tip>
  Token ID 만료 웹훅을 활용하면 토큰 기반 플로우의 보안성과 추적 가능성을 크게 향상시킬 수 있습니다.
</Tip>