> ## 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 expiration webhook

> Guide for webhook events triggered when Token IDs expire

## Overview

The Token ID expiration webhook is automatically sent when a Token ID expires based on the Token Expiration conditions you configured. This allows you to track token lifecycle and prevent token reuse issues.

<Note>
  * Token ID expiration webhooks are only sent when Token Expiration settings are enabled in your project.
  * Webhooks are sent to the Webhook URL registered in your ID check project. Learn how to register webhooks [here](/en/idcheck/webhooks/overview#2-register-webhook-events).
  * The webhook trigger is `token_expired`.
</Note>

## Supported services

Token ID expiration webhooks are supported in the following two pipelines:

<CardGroup cols={2}>
  <Card title="ID check" icon="id-card" href="/en/idcheck/webhooks/idcheck-token">
    Liveform-based identity verification main pipeline
  </Card>

  <Card title="FaceAuth" icon="face-smile">
    Selfie-based authentication sub-pipeline
  </Card>
</CardGroup>

Both pipelines use Token IDs, so webhooks are sent independently when tokens expire in each pipeline.

<Info>
  For detailed information about Token expiration webhooks for the ID check main pipeline, see [ID check Token expired webhook](/en/idcheck/webhooks/idcheck-token).
</Info>

## Token ID types and expiration concepts

### Pre-registered token

A method where your system generates Token IDs in advance.

<Info>
  * Tokens expire immediately after a single submission.
  * An explicit expiration concept exists.
</Info>

### Non-registered token

A method that uses tokens without pre-generation.

<Info>
  * Tokens do not have an explicit expiration.
  * Validity is verified based on previous usage at the time of use.
</Info>

## Token expiration settings

Webhook delivery depends on whether Token Expiration settings are enabled in your project. Two methods are supported:

<Tabs>
  <Tab title="Count-based">
    Manages token expiration based on usage count.

    Example: Expires after 1 use
  </Tab>

  <Tab title="Time-based">
    Manages token expiration based on time.

    Example: Expires after 24 hours
  </Tab>
</Tabs>

## Webhook delivery timing

Webhooks are sent independently from each pipeline when Token IDs expire:

* **ID check main pipeline**: At Token ID expiration
* **FaceAuth sub-pipeline**: At Token ID expiration

<Warning>
  Since each pipeline independently detects expiration events, separate webhooks may be sent for the same Token ID across different pipelines.
</Warning>

## Webhook specification

### Parameters

<ResponseField name="webhook_trigger" type="string" required>
  Webhook event trigger (fixed value: `token_expired`)
</ResponseField>

<ResponseField name="token_id" type="string" required>
  The expired Token ID
</ResponseField>

<ResponseField name="expired_condition" type="string" required>
  The configured expiration validation condition

  * `count`: Count-based expiration
  * `time`: Time-based expiration
</ResponseField>

<ResponseField name="service" type="string" required>
  Target service

  * `idCheck`: ID check main pipeline
  * `faceAuth`: FaceAuth sub-pipeline
</ResponseField>

<ResponseField name="expired_at" type="string">
  Expiration timestamp (ISO 8601 format)

  <Info>
    Only included when `expired_condition` is `count`.
  </Info>
</ResponseField>

<ResponseField name="expected_expired_at" type="string">
  Expected expiration timestamp (ISO 8601 format)

  <Info>
    Only included when `expired_condition` is `time`.
  </Info>
</ResponseField>

## Examples

### Count-based expiration

Webhook payload when a token expires based on usage count:

```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>
  The `expired_at` field indicates the exact time when the token expired.
</Check>

### Time-based expiration

Webhook payload when a token expires based on time:

```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>
  The `expected_expired_at` field indicates when the token was scheduled to expire.
</Check>

## Use cases

Token ID expiration webhooks are useful in the following scenarios:

<AccordionGroup>
  <Accordion title="Prevent token reuse">
    Detect expired tokens to block reuse attempts and log security events.
  </Accordion>

  <Accordion title="Track service logic">
    Track token lifecycle to analyze user flows and improve service quality.
  </Accordion>

  <Accordion title="Automated token management">
    Automatically generate new tokens or send notifications to users based on expiration events.
  </Accordion>
</AccordionGroup>

<Tip>
  Leveraging Token ID expiration webhooks can significantly enhance the security and traceability of your token-based flows.
</Tip>