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.

Authentication schemes

Each registered endpoint declares how DVS authenticates its outgoing requests. The scheme is set per endpoint via auth_type, with the matching parameters in auth_config. Secrets are never stored in plaintext — auth_config holds references to AWS Secrets Manager.

auth_type	What DVS sends	Required auth_config
none	No auth header.	—
hmac_signature	X-DVS-Signature: sha256=<hmac> over the body.	— (secret generated by DVS)
bearer_token	Authorization: Bearer <token>	token_secret_ref
api_key	Custom header with the key.	header_name, key_secret_ref
basic_auth	Authorization: Basic base64(user:pass)	credentials_secret_ref
oauth2_client_credentials	Authorization: Bearer <token> fetched via client credentials.	token_url, credentials_secret_ref

For basic_auth, store a secret in Secrets Manager containing {"username": "...", "password": "..."} and reference it via credentials_secret_ref. DVS resolves it at delivery time and sends the Authorization: Basic header on every webhook.

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.