Skip to main content

​
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.
  • 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.
  • The webhook trigger is token_expired.

​
Supported services

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

ID check

Liveform-based identity verification main pipeline

FaceAuth

Selfie-based authentication sub-pipeline
Both pipelines use Token IDs, so webhooks are sent independently when tokens expire in each pipeline.
For detailed information about Token expiration webhooks for the ID check main pipeline, see ID check Token expired webhook.

​
Token ID types and expiration concepts

​
Pre-registered token

A method where your system generates Token IDs in advance.
  • Tokens expire immediately after a single submission.
  • An explicit expiration concept exists.

​
Non-registered token

A method that uses tokens without pre-generation.
  • Tokens do not have an explicit expiration.
  • Validity is verified based on previous usage at the time of use.

​
Token expiration settings

Webhook delivery depends on whether Token Expiration settings are enabled in your project. Two methods are supported:
  • Count-based
  • Time-based
Manages token expiration based on usage count.Example: Expires after 1 use

​
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
Since each pipeline independently detects expiration events, separate webhooks may be sent for the same Token ID across different pipelines.

​
Webhook specification

​
Parameters

​
webhook_trigger
string
required
Webhook event trigger (fixed value: token_expired)
​
token_id
string
required
The expired Token ID
​
expired_condition
string
required
The configured expiration validation condition
  • count: Count-based expiration
  • time: Time-based expiration
​
service
string
required
Target service
  • idCheck: ID check main pipeline
  • faceAuth: FaceAuth sub-pipeline
​
expired_at
string
Expiration timestamp (ISO 8601 format)
Only included when expired_condition is count.
​
expected_expired_at
string
Expected expiration timestamp (ISO 8601 format)
Only included when expired_condition is time.

​
Examples

​
Count-based expiration

Webhook payload when a token expires based on usage count:
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"
}
The expired_at field indicates the exact time when the token expired.

​
Time-based expiration

Webhook payload when a token expires based on time:
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"
}
The expected_expired_at field indicates when the token was scheduled to expire.

​
Use cases

Token ID expiration webhooks are useful in the following scenarios:
Detect expired tokens to block reuse attempts and log security events.
Track token lifecycle to analyze user flows and improve service quality.
Automatically generate new tokens or send notifications to users based on expiration events.
Leveraging Token ID expiration webhooks can significantly enhance the security and traceability of your token-based flows.