Title & Registration Notifications — AI Agent Reference

AI Agent Reference

Compact reasoning layer. The agent reads params, schemas, types, and status codes directly from the spec. This section supplies intent, ordering, side effects, and safety not expressible in OpenAPI.

Operation intent table

operation_id	Goal
`Subscribe`	Register or replace the single callback URL that receives transaction status-change notifications.
`GetSubscription`	Read the currently registered callback URL.
`Unsubscribe`	Remove the subscription; stop notification delivery.
`SetCallbackSecurity`	Configure how Vitu authenticates itself to the caller's callback endpoint.

Prerequisite / dependency tree

Valid OAuth token (scheme: keycloak, scope: oneapi:access)
- Subscribe            requires: resolvable HTTPS callback URL
- GetSubscription      requires: nothing beyond auth (returns empty/absent if never subscribed)
- Unsubscribe          logically requires: an existing subscription
- SetCallbackSecurity  independent of subscription; recommended before trusting deliveries

Per-operation reasoning contracts

OPERATION: Subscribe
  AUTH:           REQUIRED — keycloak / oneapi:access
  PRECONDITIONS:  REQUIRED — callback URL is HTTPS and resolvable by Vitu
  SIDE_EFFECTS:   REQUIRED — creates subscription if none; otherwise REPLACES existing callback URL (singleton, not additive)
  SUCCESS_SIGNAL: OPTIONAL — confirm via GetSubscription returning the new callback URL (do not rely on status code alone)
  AGENT_NOTE:     Repeat calls are the mechanism for rotation, not duplication.

OPERATION: GetSubscription
  AUTH:           REQUIRED — keycloak / oneapi:access
  PRECONDITIONS:  none beyond auth
  SIDE_EFFECTS:   none (read-only)
  SUCCESS_SIGNAL: REQUIRED — response returns the registered callbackUrl

OPERATION: Unsubscribe
  AUTH:           REQUIRED — keycloak / oneapi:access
  PRECONDITIONS:  OPTIONAL — a subscription should exist for the call to be meaningful
  SIDE_EFFECTS:   REQUIRED — deletes subscription; notification delivery stops
  SUCCESS_SIGNAL: OPTIONAL — subsequent GetSubscription reflects no active callback

OPERATION: SetCallbackSecurity
  AUTH:           REQUIRED — keycloak / oneapi:access
  PRECONDITIONS:  REQUIRED — request body conforms to CallbackSecuritySettingsDTO
  SIDE_EFFECTS:   REQUIRED — replaces callback security config used for all future deliveries
  SUCCESS_SIGNAL: OPTIONAL — no read-back operation exists; verify by receiving a correctly-authenticated delivery
  AGENT_NOTE:     HMAC/Basic/OAuth/headers are combinable. HMAC header defaults to X-HMAC unless overridden.

Safety classification table

operation_id	Classification
`GetSubscription`	safe (read-only)
`Subscribe`	mutating (replaces callback URL)
`SetCallbackSecurity`	mutating (replaces security config)
`Unsubscribe`	irreversible within this API (stops delivery; requires re-subscribe to restore)

Failure-handling rules

ON_FAILURE_AUTH:
  MEANS:    token missing/expired/invalid
  RETRY:    yes, once
  STRATEGY: obtain fresh token, retry once
  STOP:     if second attempt also auth-fails

ON_FAILURE_VALIDATION:
  MEANS:    malformed request (e.g. non-HTTPS/unresolvable callback URL, bad body)
  RETRY:    no
  STRATEGY: inspect Errors[].message, correct input, resubmit
  STOP:     immediately; do not retry unchanged

ON_FAILURE_NOT_FOUND:
  MEANS:    no explicit not-found response is defined in the spec
  RETRY:    no
  STRATEGY: treat absent subscription state via GetSubscription instead
  STOP:     immediately

ON_FAILURE_RATE_LIMIT:
  MEANS:    TooManyRequests response
  RETRY:    yes
  STRATEGY: wait for window reset; honor Retry-After if present; exponential backoff otherwise
  STOP:     after a bounded number of attempts

ON_FAILURE_SERVER:
  MEANS:    server-side error response
  RETRY:    yes
  STRATEGY: exponential backoff with jitter and ceiling
  STOP:     after retry ceiling reached; escalate to [email protected]

Workflow recipes

RECIPE: Establish notifications

1. Acquire token (keycloak / oneapi:access)
2. Subscribe (HTTPS callback URL)
3. SetCallbackSecurity (configure HMAC/Basic/OAuth/headers)
4. GetSubscription (confirm callbackUrl)

RECIPE: Rotate callback endpoint

1. Subscribe (new HTTPS URL)   # replaces existing
2. GetSubscription             # confirm replacement
  NOTE: keep receiver accepting old+new security during transition

RECIPE: Rotate callback security

1. SetCallbackSecurity (new config)
  NOTE: no read-back; verify via a correctly-authenticated delivery

RECIPE: Tear down

1. Unsubscribe
2. GetSubscription             # confirm no active callback