Runnable Human Review SDK examples

Each supported SDK includes a runnable callback receiver. Every receiver uses the same callback path, published v1 wire contract, durable-receipt meaning, and application milestones:

ready → waiting_for_review → received → applied → acknowledged

These are maintainer examples. Their commands run from a checkout of the VeriProof SDK source repository. To add human review to your own application, use the SDK review runtime: pass review options to govern, save the checkpoint from the review_required result, and let the review runtime receive callbacks and resume the action. See the Developer tab in Core Human Review by role and your SDK guide, such as Add human review for Python.

Begin with the review brief

The runnable receivers begin after VeriProof has created a case. In a real application, the path starts earlier:

Select the published human-input profile by its stable key.
Build a short review brief with an execution summary, proposed-action summary, and usually three to six typed business facts.
Save the application checkpoint, protected payload, captured request, and response binding together.
Create the review case and leave the workflow paused.

When you pass review options to govern, the core SDK builds the brief, the captured request, and the checkpoint for you.

The application supplies the facts it understands. It does not copy profile fields or calculate their digests, and it does not need a VeriProof session-step ID. Application references are opaque labels, not links or proof. VeriProof adds the policy reason and authorized captured-session evidence in the portal. Keep raw tool arguments, prompt history, secrets, and the protected payload in application storage.

These examples use loopback listeners and local durable stores for synthetic testing. Replace the store, workload credential provider, and local listener with production infrastructure before deployment.

What the examples prove

The callback request is POST /v1/review-outcomes. Every example:

reads the untouched request bytes;
verifies the timestamp and VeriProof’s signature, then the schema and exact continuation binding, before trusting JSON;
stores an accepted outcome before returning 2xx; and
distinguishes first acceptance, exact replay, and conflicting delivery.

The full continuation examples, including Python, also let a worker claim the directive, revalidate current policy, apply the protected action once, and acknowledge the result. The .NET receiver example stops at durable callback acceptance.

The customer application team owns the production listener, durable store, worker, revision path, and protected side effect. The listener must only verify, store, signal the worker, and respond. For typed outcomes, follow the lifecycle response and resume-mode matrix; route_to_revision enters application-owned revision work and does not execute the superseded protected payload.

A durable callback receipt does not prove that the protected action ran. VeriProof may show Application resumed only after the execution acknowledgment says resumed.

Shared configuration meaning

Use the configuration names in your language’s column. The examples share the same concepts, but some runtime names differ.

Meaning	TypeScript	Python	.NET	Go	Java	Rust
Tenant	`VERIPROOF_TENANT_ID`	From the SDK key	`VERIPROOF_TENANT_ID`	`VERIPROOF_TENANT_ID`	`VERIPROOF_TENANT_ID`	`VERIPROOF_TENANT_ID`
Application	`VERIPROOF_APPLICATION_ID`	From the SDK key	`VERIPROOF_APPLICATION_ID`	`VERIPROOF_APPLICATION_ID`	`VERIPROOF_APPLICATION_ID`	`VERIPROOF_APPLICATION_ID`
Environment	`VERIPROOF_ENVIRONMENT`	From the SDK key	`VERIPROOF_ENVIRONMENT`	`VERIPROOF_ENVIRONMENT`	`VERIPROOF_ENVIRONMENT`	`VERIPROOF_ENVIRONMENT`
VeriProof API	`VERIPROOF_ENDPOINT`	`VERIPROOF_ENDPOINT`	Not used by the receiver	`VERIPROOF_ENDPOINT`	`VERIPROOF_ENDPOINT`	`VERIPROOF_ENDPOINT` for server revalidation
Application credential	`VERIPROOF_APPLICATION_CREDENTIAL`	`VERIPROOF_API_KEY`	Not used by the receiver	`VERIPROOF_API_KEY`	`VERIPROOF_API_KEY`	`VERIPROOF_API_KEY` for server revalidation
Published signing keys	Loaded from `VERIPROOF_ENDPOINT`	Loaded from `VERIPROOF_ENDPOINT`	Loaded from `VERIPROOF_ENDPOINT`	Loaded from `VERIPROOF_ENDPOINT`	Loaded from `VERIPROOF_ENDPOINT`	Loaded from `VERIPROOF_ENDPOINT`
Pinned signing keys (optional)	`VERIPROOF_WEBHOOK_KEY_SET`	`VERIPROOF_WEBHOOK_KEY_SET`	`VERIPROOF_WEBHOOK_KEY_SET`	`VERIPROOF_WEBHOOK_KEY_SET`	`VERIPROOF_WEBHOOK_KEY_SET`	`VERIPROOF_WEBHOOK_KEY_SET`
Registration version	`VERIPROOF_CALLBACK_REGISTRATION_VERSION`	From the signed callback	From the signed callback	From the signed callback	From the review case	`VERIPROOF_CALLBACK_REGISTRATION_VERSION`
Listener	`VERIPROOF_CALLBACK_BIND_PORT`	`VERIPROOF_CALLBACK_BIND` and `VERIPROOF_CALLBACK_PORT`	`ASPNETCORE_URLS`	`VERIPROOF_CALLBACK_ADDRESS`	`VERIPROOF_CALLBACK_BIND_PORT`	`VERIPROOF_CALLBACK_BIND_PORT`

Do not save an application credential with the checkpoint. Resolve a current credential for each server call, including calls made after a long pause.

Run one receiver

These maintainer commands run from the root of the VeriProof SDK source repository. Use only synthetic identities, a non-production callback registration, and an isolated store.

Each receiver checks callbacks with the signing keys VeriProof publishes. The commands below pin the key set from a local VeriProof Ingest API so the receiver works offline. To load the keys from a hosted endpoint instead, leave VERIPROOF_WEBHOOK_KEY_SET unset and point the endpoint setting at it.

TypeScript

Example: sdk/typescript/veriproof-sdk-core/examples/human-review-receiver.mjs


Set-Location sdk/typescript/veriproof-sdk-core
npm install
npm run build
$env:VERIPROOF_TENANT_ID='tenant-test'
$env:VERIPROOF_APPLICATION_ID='application-test'
$env:VERIPROOF_ENVIRONMENT='local'
$env:VERIPROOF_CALLBACK_REGISTRATION_VERSION='1'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:VERIPROOF_ENDPOINT='http://localhost:5100'
$env:VERIPROOF_APPLICATION_CREDENTIAL='synthetic-local-application-key'
$env:VERIPROOF_CALLBACK_BIND_HOST='127.0.0.1'
$env:VERIPROOF_CALLBACK_BIND_PORT='18083'
$env:VERIPROOF_CONTINUATION_STORE_PATH="$PWD\.veriproof\typescript-review-state.json"
$env:VERIPROOF_PROTECTED_MARKER_DIRECTORY="$PWD\.veriproof\typescript-markers"
node examples/human-review-receiver.mjs

The Node example reads the request stream into bytes and gives the untouched bytes to HumanReviewOutcomeReceiver. For Express, use the route-scoped raw-body pattern.

Python

Example: sdk/python/veriproof-sdk/examples/human-review-webhook/app.py

This example runs the whole round trip. agent.py governs an invoice payment and saves the review checkpoint. app.py passes each signed callback to the SDK review runtime, and its worker resumes the payment once and acknowledges the result. Checkpoints and outcomes are stored durably, so either process can stop and restart at any point.

Start the callback endpoint and worker:


$env:VERIPROOF_API_KEY='<application key>'
$env:VERIPROOF_ENDPOINT='http://localhost:5100'
$env:VERIPROOF_ALLOW_LOOPBACK_HTTP='true'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:VERIPROOF_CALLBACK_BIND='127.0.0.1'
$env:VERIPROOF_CALLBACK_PORT='18084'
$env:VERIPROOF_REVIEW_STORE="$PWD\.veriproof\python-review-state.db"
$env:PAYMENTS_DB="$PWD\.veriproof\python-payments.db"
uv run --project sdk/python/veriproof-sdk python sdk/python/veriproof-sdk/examples/human-review-webhook/app.py

In a second terminal with the same settings, request a payment:


$env:VERIPROOF_REVIEW_PROFILE='<review profile key>'
uv run --project sdk/python/veriproof-sdk python sdk/python/veriproof-sdk/examples/human-review-webhook/agent.py --invoice INV-10024 --supplier SUP-GLOBEX --amount 21400

Register http://127.0.0.1:18084/v1/review-outcomes for local testing. When a rule sends the payment for review, decide it in the portal and the worker pays the invoice. VERIPROOF_ALLOW_LOOPBACK_HTTP is for local tests only; use HTTPS for a deployed receiver.

Add --hosted-store to both commands to keep checkpoints and outcomes in VeriProof instead of VERIPROOF_REVIEW_STORE. To scale out, run app.py --no-worker for the listener and worker.py for each worker.

The example reads the raw request body before parsing. An ASGI route must call await request.body() and pass those bytes with every received header to the review runtime. See the ASGI raw-body requirement.

.NET

Example: sdk/dotnet/Veriproof.Sdk.Core/examples/human-review-webhook


$env:VERIPROOF_TENANT_ID='tenant-test'
$env:VERIPROOF_APPLICATION_ID='application-test'
$env:VERIPROOF_ENVIRONMENT='test'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:ASPNETCORE_URLS='http://127.0.0.1:18085'
$env:VERIPROOF_REVIEW_STORE="$PWD\.veriproof\dotnet-review-state.db"
.\vdev.ps1 build -What sdk-dotnet
dotnet run --no-build --project sdk/dotnet/Veriproof.Sdk.Core/examples/human-review-webhook/Veriproof.HumanReviewWebhook.Example.csproj

The Minimal API route copies HttpRequest.Body to bytes before calling HumanReviewOutcomeReceiver. ASP.NET owns the host and route; it is not a dependency of Veriproof.Sdk.Core.

Go

Example: sdk/go/veriproof-sdk/examples/human_review_webhook/main.go

The Go example stores callbacks and checkpoints in SQLite. Run protected work from a separate worker after revalidation.


Set-Location sdk/go/veriproof-sdk
$env:VERIPROOF_API_KEY='<application key>'
$env:VERIPROOF_ENDPOINT='http://localhost:5100'
$env:VERIPROOF_TENANT_ID='tenant-test'
$env:VERIPROOF_APPLICATION_ID='application-test'
$env:VERIPROOF_ENVIRONMENT='test'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:VERIPROOF_CALLBACK_ADDRESS='127.0.0.1:18086'
$env:VERIPROOF_REVIEW_STORE="$PWD\.veriproof\go-review-state.db"
go run ./examples/human_review_webhook

Register http://127.0.0.1:18086/v1/review-outcomes for local testing. Use durable storage and HTTPS for a deployed receiver.

Java

Example: sdk/java/examples/human-review-webhook


$env:VERIPROOF_TENANT_ID='tenant-test'
$env:VERIPROOF_APPLICATION_ID='application-test'
$env:VERIPROOF_ENVIRONMENT='test'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:VERIPROOF_ENDPOINT='http://localhost:5100'
$env:VERIPROOF_API_KEY='synthetic-local-application-key'
$env:VERIPROOF_CALLBACK_BIND_HOST='127.0.0.1'
$env:VERIPROOF_CALLBACK_BIND_PORT='18087'
$env:VERIPROOF_CONTINUATION_STORE_PATH="$PWD\.veriproof\java-review-state"
$env:VERIPROOF_PROTECTED_MARKER_DIRECTORY="$PWD\.veriproof\java-markers"
$env:VERIPROOF_E2E_CONTROL_ENABLED='true'
mvn -f sdk/java/examples/human-review-webhook/pom.xml compile exec:java

The example uses the JDK HTTP server and gives the untouched body bytes to ReviewCallbackReceiver. The application owns the host and route; no web framework is added to veriproof-sdk-core.

Rust

Example: sdk/rust/crates/veriproof-sdk/examples/human_review_receiver.rs


Set-Location sdk/rust
$env:VERIPROOF_TENANT_ID='tenant-test'
$env:VERIPROOF_APPLICATION_ID='application-test'
$env:VERIPROOF_ENVIRONMENT='test'
$env:VERIPROOF_CALLBACK_REGISTRATION_VERSION='1'
$env:VERIPROOF_WEBHOOK_KEY_SET=(Invoke-WebRequest 'http://localhost:7074/.well-known/veriproof-webhook-keys.json').Content
$env:VERIPROOF_CALLBACK_BIND_HOST='127.0.0.1'
$env:VERIPROOF_CALLBACK_BIND_PORT='18088'
$env:VERIPROOF_CONTINUATION_STORE_PATH="$PWD\.veriproof\rust-review-state.json"
$env:VERIPROOF_PROTECTED_MARKER_DIRECTORY="$PWD\.veriproof\rust-markers"
$env:VERIPROOF_E2E_TEST_MODE='true'
$env:VERIPROOF_E2E_CONTROL_ENABLED='true'
$env:VERIPROOF_E2E_CONTROL_TOKEN='synthetic-local-control-token'
cargo +1.96.0 run --locked --package veriproof-sdk --example human_review_receiver

The Axum route gives the untouched body bytes and callback headers to the Human Review runtime. The test controls require loopback and explicit test mode.

Use the shared conformance harness

This maintainer tool is part of the VeriProof SDK source repository. The harness builds and launches the installed artifacts for all six languages, gives each process an isolated port and durable store, sends the fixed signed fixture, and checks duplicate, conflict, restart, lost-checkpoint, and multi-branch behavior.


Set-Location sdk/human-review-e2e
npm test
npm run gate

npm run gate is the installed-package synthetic conformance lane. It does not replace the separate server-driven release lane. npm run gate:server must create a real server case, Inbox item, authorized decision, queued callback, durable receipt, execution acknowledgment, and correlated audit evidence before that wider gate can pass.

Before adapting an example to a durable application worker, read Recover a long-paused continuation for per-request credential refresh, exact branch binding, lost-checkpoint handling, and restart recovery.

The control routes used by the harness exist only when both VERIPROOF_E2E_CONTROL_ENABLED=true and VERIPROOF_ENVIRONMENT=test. They bind to loopback and are not production management endpoints.

Before deployment

Replace each local file, SQLite, or in-memory adapter with the application’s transactional durable store.
Use workload identity or an OAuth client-credentials provider with review-continuations.write; refresh credentials for every server call.
Use public HTTPS and register the exact tenant, application, environment, domain, port, and callback path in VeriProof.
Keep callback receipt fast. Queue application work after the durable write.
Use protectedActionId in the same transaction as the protected side effect.
Monitor callbacks, incidents, missing acknowledgments, and key expiry.
Complete your organization’s release review and confirm approval for real customer data.