Saltar al contenido principal

​
Descripción general

El webhook de expiración de Token ID se envía automáticamente cuando un Token ID expira según las condiciones de expiración de token que configuró. Esto le permite rastrear el ciclo de vida de los tokens y prevenir problemas de reutilización de tokens.
  • Los webhooks de expiración de Token ID solo se envían cuando la configuración de expiración de token está habilitada en su proyecto.
  • Los webhooks se envían a la URL de webhook registrada en su proyecto de ID Check. Aprenda cómo registrar webhooks aquí.
  • El trigger del webhook es token_expired.

​
Servicios compatibles

Los webhooks de expiración de Token ID son compatibles en los siguientes dos pipelines:

ID check

Canal principal de verificación de identidad basado en Liveform

FaceAuth

Sub-pipeline de autenticación basado en selfie
Ambos pipelines utilizan Token ID, por lo que los webhooks se envían de forma independiente cuando los tokens expiran en cada pipeline.
Para información detallada sobre los webhooks de expiración de token del pipeline principal de ID Check, consulte Webhook de token expirado de ID Check.

​
Tipos de Token ID y conceptos de expiración

​
Token preregistrado

Un método en el que su sistema genera Token ID de antemano.
  • Los tokens expiran inmediatamente después de un único envío.
  • Existe un concepto explícito de expiración.

​
Token no registrado

Un método que utiliza tokens sin generación previa.
  • Los tokens no tienen una expiración explícita.
  • La validez se verifica según el uso previo en el momento de uso.

​
Configuración de expiración de token

La entrega de webhooks depende de si la configuración de expiración de token está habilitada en su proyecto. Se admiten dos métodos:
Gestiona la expiración de tokens según el conteo de uso.Ejemplo: Expira después de 1 uso

​
Momento de entrega del webhook

Los webhooks se envían de forma independiente desde cada pipeline cuando los Token ID expiran:
  • Pipeline principal de ID Check: En la expiración del Token ID
  • Sub-pipeline de FaceAuth: En la expiración del Token ID
Dado que cada pipeline detecta eventos de expiración de forma independiente, pueden enviarse webhooks separados para el mismo Token ID en diferentes pipelines.

​
Especificación del webhook

​
Parámetros

​
webhook_trigger
string
requerido
Trigger del evento de webhook (valor fijo: token_expired)
​
token_id
string
requerido
El Token ID expirado
​
expired_condition
string
requerido
La condición de validación de expiración configurada
  • count: Expiración basada en conteo
  • time: Expiración basada en tiempo
​
service
string
requerido
Servicio objetivo
  • idCheck: Pipeline principal de ID Check
  • faceAuth: Sub-pipeline de FaceAuth
​
expired_at
string
Marca de tiempo de expiración (formato ISO 8601)
Solo se incluye cuando expired_condition es count.
​
expected_expired_at
string
Marca de tiempo de expiración esperada (formato ISO 8601)
Solo se incluye cuando expired_condition es time.

​
Ejemplos

​
Expiración basada en conteo

Payload del webhook cuando un token expira según el conteo de uso:
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"
}
El campo expired_at indica el momento exacto en que el token expiró.

​
Expiración basada en tiempo

Payload del webhook cuando un token expira según el tiempo:
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"
}
El campo expected_expired_at indica cuándo estaba programada la expiración del token.

​
Casos de uso

Los webhooks de expiración de Token ID son útiles en los siguientes escenarios:
Detecte tokens expirados para bloquear intentos de reutilización y registrar eventos de seguridad.
Rastree el ciclo de vida de los tokens para analizar los flujos de usuarios y mejorar la calidad del servicio.
Genere automáticamente nuevos tokens o envíe notificaciones a los usuarios basándose en eventos de expiración.
Aprovechar los webhooks de expiración de Token ID puede mejorar significativamente la seguridad y la trazabilidad de sus flujos basados en tokens.