Webhooks

For async requests (all validation, optionally classification), DVS delivers results via HTTP POST webhooks to an endpoint you register at onboarding. Every webhook is HMAC-signed so you can verify it came from DVS.

High-level

1. 1You register an endpoint

   Provide an HTTPS URL during onboarding. OSIGU configures it in DVS and issues a shared secret.

2. 2You make an async API call

   POST /v1/classification-requests with mode=async, or POST /v1/provider-validation-requests. DVS responds 202 Accepted.

3. 3DVS processes in the background

   Typical: 3-5s for classification, 15-60s for validation.

4. 4DVS POSTs to your endpoint

   Headers include X-DVS-Signature (HMAC), X-DVS-Event-Id, X-DVS-Event-Type. Body is the event payload.

5. 5You verify the signature and respond 200

   Within 10 seconds. If you take longer or return non-2xx, DVS retries with backoff.

Event types

Event	When emitted
classification.completed	Classification finished successfully (including type=UNKNOWN).
classification.failed	Technical error during classification.
validation.completed	Validation finished with a verdict (APPROVED / REJECTED / ERROR).
validation.failed	Technical error during validation (extraction failed, validator outage, internal error).
test.ping	Synthetic test event sent on demand to verify connectivity.

See Webhook Events for full payload schemas.

Retry policy

3 attempts with exponential backoff: immediate, +60s, +300s. If all 3 fail, the event goes to DVS dead-letter queue and you can poll the resource via GET to recover.

After 10 consecutive failures on your endpoint, DVS auto-disables it to prevent runaway traffic. Reactivation requires admin action — contact OSIGU.

Multiple endpoints, event filtering

Your tenant can have N webhook endpoints registered (e.g., one per environment, one per event type). Each can filter by event types. See Implement Webhook Receiver.