Return to your app after the capture
When the person has taken their photos, tryVidimus can bring them back to your application, and tell your server that the capture is finished.
What the person sees
After the last photo, the capture page shows its completion text, then a message such as "You will be taken back to app.example.com in 4 s", with two buttons: go back now, or stay on the page. After 4 seconds the person is taken to your address, with the identifiers of the proof added to it. Without a return address, the person stays on the completion page.
1. Declare your site
A capture link must never be able to send a person to a site you did not choose. So you first declare the sites you accept, as origins (https://app.example.com, with no path), up to 20. There is one list for test and one for live (the key you use decides which one), and changing it needs the manage_settings scope on your key. Until you declare something, no return address is accepted. In your account (the Sites page), you can edit the test list yourself; the live list is shown there read-only for now: set it with the API using a live key, or ask us.
$ curl -X PATCH https://api.tryvidimus.com/v1/settings \ -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_return_origins":["https://app.example.com"]}' { "allowed_return_origins": ["https://app.example.com"] }
2. Pass the return address
Add return_url when you create the capture session. Its site must be in your list, otherwise the call fails with 422 return_url_not_allowed and no session is created. Only https is accepted; http://localhost is accepted for sandbox keys only, for development.
$ curl -X POST https://api.tryvidimus.com/v1/capture-sessions \ -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"external_reference":"booking_4471","party":"provider","return_url":"https://app.example.com/bookings/4471/capture-done"}'
3. What your page receives
Two parameters are added to your address: proof_id, the proof being created, and session_id. Nothing else: never your own reference, never the capture token. Treat them as hints, not as proof, since anyone can type an address. To be sure the capture happened, read the proof from the API with the proof_id, or rely on the webhook below.
https://app.example.com/bookings/4471/capture-done
?proof_id=prf_01m4akapdbe8e8qq3er9r5qwyj
&session_id=cps_01m4akapdbe8e8qq3er9r5qwyj
4. The reliable signal: the webhook
The redirection is a convenience: the person can close the page before it happens. The reliable signal is the capture_session.completed event, sent to your server a few seconds after the files are saved and before the proof is sealed. Subscribe your endpoint to it: an endpoint created before this event existed does not receive it until you add it to its events. The proof is not sealed yet, so wait for proof.sealed before relying on it. The event has the same identifier on every retry, so you can ignore duplicates.
{
"event": "capture_session.completed",
"session_id": "cps_01m4akapdbe8e8qq3er9r5qwyj",
"proof_id": "prf_01m4akapdbe8e8qq3er9r5qwyj",
"external_reference": "booking_4471",
"party": "provider",
"stage": "pickup",
"completed_at": "2026-10-08T10:00:00.123Z"
}
From the command line
The CLI does the same without writing a request: declare your sites, then pass --return-url when you open a session. Changing the list asks for --yes, because it replaces the previous one.
$ tryvidimus settings set-return-origins --origins https://app.example.com --yes $ tryvidimus sessions create --reference booking_4471 --party provider \ --return-url https://app.example.com/bookings/4471/capture-done
Never rely on the redirection alone: always wait for the webhook, or read the proof from the API.