Skip to main content
UIP delivers results to the webhook URL configured for your business. For the delivery model and signature verification, see Webhooks; this page is the event payload reference.

​
Headers (every delivery)

HeaderDescription
X-UIP-EventEvent name (e.g. step.completed)
X-UIP-TimestampUnix seconds when signed
X-UIP-SignatureHMAC-SHA256(webhook_secret, "{timestamp}.{raw_body}"), hex
X-UIP-Delivery-IdStable per-event id — dedupe on this
Every payload is { "event": "...", "data": { ... } }, and data always echoes session_id, plus your client_reference_id and metadata when set.

​
step.completed

Fires once per step, in order, the moment it verifies. The result fields depend on the step’s primitive. 
{
  "event": "step.completed",
  "data": {
    "session_id": "sess_abc123",
    "client_reference_id": "order_4815",
    "stage": 0,
    "primitive": "identify",
    "audit_id": "sess_abc123_0",
    "claims": { "first_name": "Jane", "last_name": "Doe", "country": "US" }
  }
}
​
stage
integer
Zero-based index of the completed step.
​
primitive
string
The step’s primitive.
​
audit_id
string
Id of this step’s audit record — fetch the proof via GET /v1/audits/{id}.
​
claims
object
identify only — the disclosed blocks.
​
satisfied
boolean
age_verify only — the threshold result. The birth date is never included.
​
min_age
integer
age_verify only — the threshold that was checked.
​
signature
string
sign/light_sign only — the device signature.
​
document_hash
string
sign/light_sign only — the hash that was signed.

​
session.completed

All steps verified. 
{ "event": "session.completed", "data": { "session_id": "sess_abc123", "status": "completed" } }

​
session.stopped

You ended the session at a gate via stop. 
{ "event": "session.stopped", "data": { "session_id": "sess_abc123", "status": "stopped" } }

​
session.failed

A step failed verification, funds ran out, or an internal error occurred. 
{ "event": "session.failed", "data": { "session_id": "sess_abc123", "reason": "insufficient_funds" } }
​
reason
string
e.g. a verification error message, insufficient_funds, or internal_error.
Always verify the signature over the raw body and dedupe on X-UIP-Delivery-Id before acting — delivery is at-least-once.