Tipos de eventos
Los payloads de webhook describen una transición de estado de un proceso. Esta página documenta el esquema del payload y la enumeración completa de los valores de lastEvent.
Esquema del payload
| Campo | Tipo | Descripción |
|---|---|---|
processId | string (UUID) | ID de la transacción. |
state | string | Estado actual de la transacción. Actualmente: PROCESS_STATE_FINISHED. |
result | string | Resultado del proceso finalizado. Presente cuando state=PROCESS_STATE_FINISHED. Valores posibles: ok, expired, invalid_identity. |
flow | string | Flujo que se ejecutó para esta transacción (por ejemplo, id, idtoken). |
lastEvent | string | Último evento de la transacción. Se devuelve solo cuando result=expired. |
lastEventDescription | string | Descripción legible de lastEvent. Se devuelve solo cuando result=expired. |
El campo state en los payloads de webhook usa el prefijo PROCESS_STATE_*. Este es un vocabulario distinto al de los campos result y status devueltos por el endpoint GetProcess, que usan PROCESS_RESULT_*. No los trate como intercambiables.
Ejemplo de payload
Finalizado — exitoso
{
"processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
"state": "PROCESS_STATE_FINISHED",
"flow": "id",
"result": "ok"
}
Finalizado — expirado
{
"processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
"state": "PROCESS_STATE_FINISHED",
"flow": "id",
"result": "expired",
"lastEvent": "EVENT_TYPE_SESSION_ENDED",
"lastEventDescription": "Session ended by timeout or by new session created"
}
Enumeración de lastEvent
La lista completa de valores que pueden aparecer en lastEvent:
| Evento | Descripción |
|---|---|
EVENT_TYPE_PROCESS_CREATED | Proceso creado |
EVENT_TYPE_QR_CODE_READ | Código QR leído |
EVENT_TYPE_PROCESS_STARTED_BY_USER | Proceso iniciado por el usuario |
EVENT_TYPE_IDENTITY_VALIDATION_STEP_FINISHED | Paso de validación de identidad finalizado |
EVENT_TYPE_DOCUMENT_STEP_STARTED | Paso de documento iniciado |
EVENT_TYPE_DOCUMENT_PHOTO_CAPTURED | Foto del documento tomada |
EVENT_TYPE_DOCUMENT_UPLOADED_FROM_GALLERY | Documento subido desde la galería |
EVENT_TYPE_DOCUMENT_STEP_FINISHED | Paso de documento finalizado |
EVENT_TYPE_SESSION_ENDED | Sesión finalizada por tiempo de espera o por creación de una nueva sesión |
EVENT_TYPE_ERROR_ON_DOCUMENT_STEP | Error en el paso de documento |
El conjunto de eventos puede evolucionar. Trate los eventos a los que reacciona su endpoint como configuración, no como constantes codificadas — de esa forma, los nuevos eventos pueden habilitarse sin necesidad de un despliegue.
Lectura del resultado completo del proceso
El payload del webhook indica que un proceso ha finalizado e incluye el resultado de alto nivel en el campo result. Para obtener los detalles completos — datos de captura, puntuaciones biométricas, campos del documento, etc. — llame al endpoint GetProcess correspondiente:
- Para flujos visuales / Web y Nativo: consulte Referencia de API > Web y Nativo > GET /v1/process/{id}.
- Para flujos no visuales / API: consulte Referencia de API > API > GET /processes/v1/{id}.