Skip to content
One-Shot
/
/
/
Asynchronous flow
Last updated

Asynchronous mode overview

Asynchronous mode provides more transparency about background processing and shorter API response times. The sequence of operations is the same as the classic workflow, but when creating the signature request you set useasync=true and provide a callback URL. The API returns quickly; processing continues on the server, and status changes can be sent to your webhook.

Total processing time is the same as in the classic flow; only the way the client waits for completion changes (via webhook instead of a long-running sign call response).

Enabling asynchronous mode

When calling Create (Create Request, POST /oneshot/api/v1/create), add:

  • useasync=true
  • callback=https://your-server.com/your-webhook-path

The callback URL receives HTTP POST notifications at each request status change. The definitive webhook URL for production must be set in your Registration Authority (RA) by the Operations Department; the parameter in the API is especially useful for testing.

Steps (same as classic, with async Create Request)

  1. Retrieve an existing token for the RAO — List Tokens (GET /oneshot/api/v1/tokens).

  2. Create a new digital signature request (async) — Create (POST /oneshot/api/v1/create) with the same form fields as classic, plus useasync=true and callback=<url>. Response includes asyncmode: true and request pk.

  3. Upload documents — Upload Document (POST /oneshot/api/v1/document/{request_pk}).

  4. Retrieve service contract — Get Request Contract (GET /oneshot/api/v1/contract/{request_pk}).

  5. Generate OTP (Uanataca SMS only) — Generate OTP (POST /oneshot/api/v1/otp/{request_pk}).

  6. Sign the document — Sign (POST /oneshot/api/v1/sign/{request_pk}) with OTP or other auth. The API may return quickly with a message such as "Your documents are going to be signed"; completion is reflected in webhook payloads.

  7. Retrieve signed documents — After the webhook or status indicates completion, call Get Document (GET /oneshot/api/v1/document/{request_pk}/{document_uid}?document_type=signed) for each document.

  8. Delete documents from the Optimizer — Delete Document (DELETE /oneshot/api/v1/document/{request_pk}/{document_uid}) when no longer needed.

Webhook payload

Each status change triggers an HTTP POST to your callback URL with a JSON body. Fields include status (current status), date, previous_status, request (request id), registration_authority, and others. See Webhook configuration for the exact structure and sample code.

Previous page
Next page