Visão Geral dos Webhook Events

Todos os webhooks do DVS compartilham um envelope comum. Apenas o event_type e o conteúdo de data mudam de acordo com o evento.

Envelope

{
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "event_type": "<type>",
  "event_version": 1,
  "correlation_id": "<uuid>",
  "occurred_at": "2026-06-03T17:30:03.000Z",
  "data": { /* específico do evento */ }
}

Campo	Descrição
event_id	Único por evento pai da tentativa de entrega (retries reutilizam o mesmo id). Utilize-o como idempotency key.
event_type	Um dos valores listados abaixo.
event_version	Versão de schema de data. Atualmente 1.
correlation_id	UUID que conecta eventos relacionados. Para a cadeia classification → validation, ambos compartilham o id da classification. Para eventos isolados, é igual ao id do recurso.
occurred_at	Timestamp ISO 8601 UTC.

Catálogo de eventos

classification.completed

A classification foi concluída. data.type é um dos valores do catálogo ou UNKNOWN.

classification.failed

A classification não pôde ser executada (indisponibilidade do engine, falha de parsing, etc.).

validation.completed

A validation foi concluída com um veredito. data.final_status é APPROVED, REJECTED ou ERROR.

validation.failed

A validation falhou tecnicamente (extração falhou, indisponibilidade do validator, erro interno).

Além de test.ping, um evento sintético usado para verificar a conectividade durante o onboarding.

Headers

Header	Exemplo
X-DVS-Signature	t=1748884800,v1=a8d3e8b1c2...
X-DVS-Signature-Timestamp	1748884800
X-DVS-Event-Id	evt_550e8400-...
X-DVS-Event-Type	validation.completed
X-DVS-Event-Version	1
X-DVS-Delivery-Attempt	1, 2 ou 3
X-DVS-Correlation-Id	UUID

Veja Verify HMAC Signatures para saber como validar X-DVS-Signature.