Title & Registration - Notifications

1. Overview & Introduction

The Title & Registration — Notifications API lets you receive asynchronous event notifications when the status of a submitted title and registration transaction changes. Instead of repeatedly polling a transaction API for status, you register a callback endpoint once, and Vitu pushes updates to you as they occur.

The domain model is intentionally small. The central concept is a subscription: a single, tenant-scoped registration that binds your credentials to one callback URL — the HTTPS endpoint Vitu calls when a transaction status change occurs. A subscription is effectively a singleton per authenticated caller: subscribing again replaces the callback target rather than creating a second subscription. Alongside the subscription sits callback security configuration, which describes how Vitu authenticates itself to your callback endpoint (so you can verify that incoming notifications genuinely originate from Vitu).

The API is served across three environments — production, staging, and test — distinguished by an environment segment in the server URL. See the spec's servers block for the exact URLs and the environment enumeration; do not hardcode the values, since they can change.

Access and sensitivity considerations up front: All operations require an OAuth 2.0 bearer token (client-credentials flow). Your callback URL must be HTTPS and publicly resolvable by Vitu. Because notification payloads relate to title and registration activity, treat your callback endpoint as receiving regulated transaction data and secure it accordingly (see Callback security and Data sensitivity).

Corresponding Title & Registration products: The State-Specific EVR and/or Multi-State Title & Registration products serve as the complementary offerings to this Notifications service. Together, the transaction and notification capabilities provide a complete ecosystem for both initiating vehicle transaction requests and staying informed of relevant updates through secure, automated notifications. See those additional Title & Registration products 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 you control, ready to receive POST callbacks.
• Familiarity with the OAuth 2.0 client-credentials grant.

Shortest path to a working notification flow

1. Obtain a token. Exchange your client credentials at the token endpoint defined by the keycloak security scheme, requesting the oneapi:access scope.
2. Register your callback. Call the Subscribe operation, supplying your HTTPS callback URL. This creates (or replaces) your subscription.
3. Configure callback security. Call the SetCallbackSecurity operation so Vitu can authenticate itself to your endpoint (HMAC, Basic, OAuth, and/or custom headers — see the CallbackSecuritySettingsDTO schema).
4. Verify. Call the GetSubscription operation to confirm the registered callback URL.
5. Receive notifications. As transaction statuses change, Vitu calls your endpoint.

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

3. Authentication & Access Walkthrough

All API operations are protected by the keycloak security scheme (OAuth 2.0, client-credentials flow). The spec's securitySchemes block is the formal definition — this section covers only the operational how-to.

Obtaining credentials. Client credentials are issued by Vitu and retrievable from the Key Management area of Vitu's Developer Portal.

Obtaining a token. Use the client-credentials grant against the token URL defined in the keycloak scheme, requesting the oneapi:access scope. The response yields a bearer token.

Attaching the token. Send the token as a bearer credential in the Authorization header on every request.

Lifecycle. Tokens expire; request a new one when yours nears or reaches expiry. On a 401 response, obtain a fresh token and retry once before treating the failure as terminal. Do not retry 401 in a tight loop.

Environment differences. Each environment (production, staging, test) has its own base URL per the spec's servers block.

Only one scheme exists. There is no API-key or alternative auth path. Do not expect one.

4. Key Concepts & Glossary

How resources relate

• A subscription must exist (via Subscribe) before notifications can be delivered.
• Callback security is configured independently and governs how Vitu signs/authenticates deliveries to your endpoint. It is a peer to the subscription, not a child of it.
• Transactions originate outside this API; this API only informs you when their status changes.

Callback security options

The CallbackSecuritySettingsDTO schema supports multiple, combinable mechanisms:

• HMAC — Vitu computes an HMAC/SHA256 signature over the payload using your shared key and sends it in a header (default X-HMAC, overridable). Verify it on receipt.
• Basic auth — Vitu presents a login/password.
• Client-credentials OAuth — Vitu obtains a token from your token endpoint before calling you.
• Security headers — arbitrary name/value headers Vitu attaches to each delivery.

See the spec's HmacSettingsDTO, BasicAuthSettingsDTO, ClientCredentialsOAuthSettingsDTO, and HeaderDTO schemas for exact fields.

5. Common Use Cases & Integration Patterns

Scenario A - Stand up event-driven notifications (webhook, not polling)

This API is push-based by design. The recommended pattern is:

1. Subscribe — register your HTTPS callback URL.
2. SetCallbackSecurity — configure how Vitu authenticates to you (do this before or immediately after subscribing, and before you trust incoming traffic).
3. GetSubscription — confirm the active callback URL.

Once configured, react to deliveries at your endpoint. There is no polling operation for transaction status in this spec.

Scenario B - Rotate or relocate your callback endpoint

Call Subscribe again with the new URL. Because the subscription is a singleton, this replaces the existing callback target rather than creating an additional one. Re-confirm with GetSubscription.

Scenario C - Update how deliveries are authenticated

Call SetCallbackSecurity with the new configuration. Coordinate the switchover so your receiving endpoint accepts both old and new credentials during the transition to avoid dropped notifications.

Scenario D - Stop receiving notifications

Call Unsubscribe. Deliveries cease. Re-establishing later requires calling Subscribe again.

Pattern guidance: Prefer configuring callback security before relying on delivered data. Design your receiver to be idempotent — assume a given event may be delivered more than once (see Behavioral notes).

6. Behavioral & Operational Notes

• Subscription is a singleton (replace, not append). Subscribe modifies the existing callback URL on repeat calls. Do not expect multiple concurrent callback targets.
• Asynchronous delivery. Notifications arrive out-of-band relative to whatever triggered the status change. Do not assume a status change is reflected the instant a transaction is acted upon elsewhere.
• Callback security is set independently of the subscription. Changing one does not change the other. A subscription with no security configuration will still receive deliveries — but unauthenticated — so configure security deliberately.
• HMAC header is configurable. If you rely on the default header name (X-HMAC), account for the fact that it can be overridden per your configuration.

7. Environments & Sandbox Access

The env server variable selects the environment: production, stage, and test (see servers for the authoritative segment values). Use test/stage for integration work and reserve production for live DMV filings. Credentials differ per environment — obtain and confirm them via the Key Management area of Vitu's Developer Portal.

8. Rate Limiting & Quotas

All operations can return a rate-limit response (TooManyRequests, per the spec's shared response). When you hit it, back off and retry after the window resets. The spec does not define specific numeric limits or a Retry-After header; if present at runtime, honor it. Do not hardcode limits — treat the rate-limit response as the signal.

9. Pagination Conventions

The subscription-retrieval operation accepts the shared limit and offset parameters (see the spec's LimitParam and OffsetParam). This is Vitu's standard offset/limit pagination convention. Given the subscription is effectively a singleton, pagination here is a cross-cutting convention rather than a practical necessity.

10. Error Handling & Troubleshooting

Error responses use the spec's Errors schema (an array of Error objects, each carrying a human-readable message). Handle failures by class, not by memorizing codes:

Read the message field of returned Error objects for diagnostics.

11. Data Sensitivity & Compliance Notes

Notifications concern title and registration transactions. Your callback endpoint receives data that may be regulated. Enforce HTTPS (the spec requires it for the callback URL), verify Vitu's authenticity via the configured callback security (HMAC signature verification is recommended), and restrict access to received payloads. This is handling guidance, not legal advice.

12. Support & Resources

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