Driver License Data Verification (DLDV) - Notifications

1. Overview & Introduction

The DLDV Notifications API lets you receive asynchronous event notifications when the result of a driver license data verification request becomes available. Rather than polling a verification service for completion, you register a callback URL, and Vitu delivers a notification to that URL when a result is ready.

The domain has two core concepts. A subscription is your registration of a callback URL — the destination where Vitu delivers verification-result notifications for your organization. Callback security settings describe how Vitu authenticates itself to your callback endpoint when it delivers those notifications (for example, via basic auth, HMAC signing, OAuth client credentials, custom headers, or mTLS). A subscription is the "where to deliver," and the callback security settings are the "how to deliver securely." Both are managed per authenticated caller.

The API is served across three environments — production (api), staging (api-stage), and test (api-test) — selected via the env server variable in the spec. All environments share the same operation set and contract; they differ only in the underlying data and, typically, the credentials issued to you.

Access is controlled by OAuth 2.0 client-credentials, using the security scheme named oneVituOauth in the spec. Because callbacks concern driver license verification results — a regulated, sensitive data domain — treat both the callback endpoint and the delivered payloads as sensitive. Your callback URL must use HTTPS (the spec enforces an https:// pattern), and you should configure callback security so Vitu can authenticate itself to your endpoint.

Corresponding DLDV Verification product: The DLDV Verification product serves as a complementary offering to this DLDV Notifications service. Together, the verification and notification capabilities provide a complete ecosystem for both initiating driver’s license data verification requests and staying informed of relevant updates through secure, automated notifications. See that product in the Catalog for more details.

2. Getting Started / First Call

Prerequisites

• OAuth 2.0 client credentials issued by Vitu. Obtain these from the Key Management area within Vitu's Developer Portal.
• A publicly resolvable HTTPS endpoint that can receive notification deliveries.
• The environment you intend to target (api, api-stage, or api-test).

Minimal happy path

1. Obtain a token. Use your client credentials against the token endpoint referenced by the oneVituOauth scheme to obtain an access token with the oneapi:access scope. See Authentication.
2. (Recommended) Configure callback security. Call the callback-security operation (SetCallbackSecurity) so Vitu can authenticate itself when delivering to your endpoint. Do this before subscribing if your endpoint requires authentication to accept deliveries.
3. Subscribe. Call the subscribe operation (Subscribe), providing your HTTPS callback URL. On success, Vitu records the subscription.
4. Verify. Call the get-subscription operation (GetSubscription) to confirm the callback URL Vitu has on record.
5. Receive notifications. When a verification result is available, Vitu delivers a notification to your callback URL.

Refer to the spec for the exact request and response shapes of each operation.

3. Authentication & Access Walkthrough

All operations in this API require OAuth 2.0 client-credentials authentication under the oneVituOauth scheme. This is the only scheme defined — there is no API-key or basic-auth alternative for calling the API itself. (Note: basic auth, HMAC, and OAuth appear in the callback security settings, but those govern how Vitu authenticates to your endpoint, not how you authenticate to Vitu.)

Obtaining credentials

Client credentials are issued by Vitu and retrievable from the Key Management area within Vitu's Developer Portal. Each environment uses distinct credentials; use the credentials matching your target environment.

Obtaining and attaching a token

1. Exchange your clientId/clientSecret at the token endpoint defined by the oneVituOauth scheme, requesting the oneapi:access scope.
2. Attach the returned bearer token to each API request.

Refer to the spec's securitySchemes.oneVituOauth entry for the formal scheme definition, including the token URL and scope name.

Token lifecycle

The client-credentials grant returns short-lived tokens. Cache and reuse a token until near its expiry, then request a new one. If a request fails authentication after the token should still be valid, request a fresh token once and retry; if it fails again, treat it as a credential/configuration problem rather than retrying in a loop. Token expiry values come from the token endpoint response, not from this API.

4. Key Concepts & Glossary

Callback security mechanisms

The callback security settings schema (see CallbackSecuritySettingsDTO in the spec) lets you configure how Vitu authenticates to your endpoint. Available mechanisms include basic auth, HMAC signing, OAuth client-credentials, custom security headers, and mTLS. Refer to the spec's schemas (BasicAuthSettingsDTO, HmacSettingsDTO, ClientCredentialsOAuthSettingsDTO, HeaderDTO, MtlsSettingsDTO) for the fields each mechanism requires.

Relationships & dependencies

• A subscription and callback security settings are independent records but functionally coupled: the security settings apply to deliveries made to the subscribed callback URL.
• The verification request (external to this API) is the event source; a notification exists only because a verification result became available.

5. Common Use Cases & Integration Patterns

Use case A - Start receiving notifications

Goal: Register an endpoint and begin receiving verification-result notifications.

1. SetCallbackSecurity — configure how Vitu should authenticate to your endpoint (do this first if your endpoint rejects unauthenticated requests).
2. Subscribe — register your HTTPS callback URL.
3. GetSubscription — confirm the registered URL.

Pattern: This API is webhook/push, not poll. Once subscribed, you do not call the API to retrieve results; you receive them at your callback URL. Ensure your endpoint is live and secured before subscribing to avoid dropped early deliveries.

Use case B - Rotate or update callback security

Goal: Change the credentials or mechanism Vitu uses to authenticate to your endpoint.

1. SetCallbackSecurity — submit updated settings.

Pattern: Update security settings on your endpoint and via this operation in a coordinated way to avoid a window where deliveries fail authentication. See Behavioral Notes on replace-vs-merge semantics.

Use case C - Change or verify your callback destination

Goal: Point notifications at a different endpoint, or confirm the current one.

1. GetSubscription — read the current callback URL.
2. Subscribe — register the new callback URL.

Use case D - Stop receiving notifications

Goal: Deregister your endpoint.

1. Unsubscribe — remove the subscription.

Pattern: After unsubscribing, expect no further deliveries. Any in-flight notifications already dispatched may still arrive; design your endpoint to tolerate this.

6. Behavioral & Operational Notes

• Asynchronous delivery. Notifications are delivered when a verification result is ready, on Vitu's timeline — not synchronously with any call you make here. Do not build logic that assumes immediate delivery after subscribing.
• HTTPS requirement. The callback URL must match an https:// pattern; plain HTTP is rejected by the schema.
• Endpoint must be resolvable. The subscribe operation requires a resolvable callback URL. An endpoint that is unreachable at delivery time will not receive notifications.

7. Asynchronous / Webhook / Callback Patterns

This API is fundamentally a webhook registration surface: you register a destination, and Vitu pushes notifications to it.

What the spec establishes:

• You register an HTTPS callback URL via the subscribe operation.
• You configure how Vitu authenticates to that URL via the callback-security operation.

8. Rate Limiting & Quotas

All operations can return a rate-limit response (the spec's TooManyRequests response, referencing the shared Errors schema). When you hit it, stop issuing requests and retry after the window resets.

9. Pagination Conventions

The get-subscription operation accepts standard limit/offset pagination parameters (defined in the spec as LimitParam and OffsetParam). Where pagination applies, request pages using these parameters and advance the offset until fewer than a full page is returned. Refer to the spec for the parameters' bounds and defaults.

10. Error Handling & Troubleshooting

Error responses use the spec's shared Errors schema (an array of Error entries, each with a message and optional field). Handle errors by class rather than by specific code:

Use the messages in the Errors payload for diagnostics. Refer to the spec for exact status codes and the error schema shape.

11. Data Sensitivity & Compliance Notes

Notifications concern driver license data verification results — regulated, sensitive data. Handling expectations:

• Serve your callback endpoint over HTTPS only (enforced by the spec).
• Configure callback security so Vitu can authenticate itself to your endpoint; prefer mechanisms appropriate to your risk posture (e.g. mTLS or HMAC signing).
• Validate the authenticity of every delivery before processing.
• Restrict, log, and retain notification data according to your organization's regulatory obligations.

This is guidance, not legal advice. Confirm specific compliance requirements with your own compliance function and with Vitu.

12. Support & Resources

​For any API assistance, contact Vitu's API support team at [email protected].