Tipos de evento

Os payloads de webhook descrevem uma transição de estado de processo. Esta página documenta o schema do payload e a enumeração completa dos valores de lastEvent.

Schema do payload

Campo	Tipo	Descrição
processId	string (UUID)	ID da transação.
state	string	Estado atual da transação. Atualmente: PROCESS_STATE_FINISHED.
result	string	Resultado do processo finalizado. Presente quando state=PROCESS_STATE_FINISHED. Valores possíveis: ok, expired, invalid_identity.
flow	string	Fluxo executado para esta transação (ex.: id, idtoken).
lastEvent	string	Último evento da transação. Retornado apenas quando result=expired.
lastEventDescription	string	Descrição legível de lastEvent. Retornado apenas quando result=expired.

Vocabulário de status

O campo state nos payloads de webhook usa o prefixo PROCESS_STATE_*. Este é um vocabulário distinto dos campos result e status retornados pelo endpoint GetProcess, que utilizam PROCESS_RESULT_*. Não os trate como intercambiáveis.

Exemplo de payload

Finalizado — com sucesso

{
  "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"
}

Enumeração de lastEvent

A lista completa de valores que podem aparecer em lastEvent:

Evento	Descrição
EVENT_TYPE_PROCESS_CREATED	Processo criado
EVENT_TYPE_QR_CODE_READ	QR code lido
EVENT_TYPE_PROCESS_STARTED_BY_USER	Processo iniciado pelo usuário
EVENT_TYPE_IDENTITY_VALIDATION_STEP_FINISHED	Etapa de validação de identidade concluída
EVENT_TYPE_DOCUMENT_STEP_STARTED	Etapa de documento iniciada
EVENT_TYPE_DOCUMENT_PHOTO_CAPTURED	Foto do documento capturada
EVENT_TYPE_DOCUMENT_UPLOADED_FROM_GALLERY	Documento enviado da galeria
EVENT_TYPE_DOCUMENT_STEP_FINISHED	Etapa de documento concluída
EVENT_TYPE_SESSION_ENDED	Sessão encerrada por timeout ou por nova sessão criada
EVENT_TYPE_ERROR_ON_DOCUMENT_STEP	Erro na etapa de documento

Tratamento configurável

O conjunto de eventos pode evoluir. Trate os eventos aos quais seu endpoint reage como configuração, não como constantes fixas no código — dessa forma, novos eventos podem ser habilitados sem um novo deploy.

Lendo o resultado completo do processo

O payload do webhook sinaliza que um processo foi finalizado e inclui o resultado de alto nível no campo result. Para recuperar os detalhes completos — dados de captura, pontuações biométricas, campos do documento, etc. — chame o endpoint GetProcess apropriado:

• Para fluxos visuais / Web e Nativo: consulte Referência de API > Web e Nativo > GET /v1/process/{id}.
• Para fluxos não visuais / API: consulte Referência de API > API > GET /processes/v1/{id}.