Webhook Events Overview

All DVS webhooks share a common envelope. Only the event_type and the contents of data change by event.

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": { /* event-specific */ }
}

Field	Description
event_id	Unique per delivery attempt's parent event (retries reuse the same id). Use as your idempotency key.
event_type	One of the values listed below.
event_version	Schema version of data. Currently 1.
correlation_id	UUID that links related events. For chained classification → validation, both share the classification's id. For standalone events, equals the resource id.
occurred_at	ISO 8601 UTC timestamp.

Event catalog

classification.completed

Classification finished. data.type is one of the catalog values or UNKNOWN.

classification.failed

Classification could not be performed (engine outage, parsing failure, etc.).

validation.completed

Validation finished with a verdict. data.final_status is APPROVED, REJECTED, or ERROR.

validation.failed

Validation failed technically (extraction failed, validator outage, internal error).

Plus test.ping, a synthetic event used to verify connectivity during onboarding.

Headers

Header	Example
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, or 3
X-DVS-Correlation-Id	UUID

See Verify HMAC Signatures for how to validate X-DVS-Signature.