Skip to main content
  • Token ID expiration webhooks are only sent when Token Expiration settings are enabled in your project.
  • Token expiration can be configured as count-based or time-based.

​
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.
  • Count-based
  • Time-based
Manages token expiration based on usage count.Example: Expires after 1 use

​
Webhook examples

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

​
Response fields

​
webhook_trigger
string
Webhook trigger type - token_expired indicates that the Token ID has expired
​
token_id
string
The expired Token ID
​
expired_condition
string
The configured expiration validation condition
  • count: Count-based expiration
  • time: Time-based expiration
​
service
string
Target service - idCheck (ID check main pipeline)
​
expired_at
string
Expiration timestamp (ISO 8601 format)
Only included when expired_condition is count. Indicates the exact time when the token expired.
​
expected_expired_at
string
Expected expiration timestamp (ISO 8601 format)
Only included when expired_condition is time. 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.