Review Queue and Webhooks

Handle borderline review decisions with polling plus push webhooks for your manual review queue.

• Register a callback_url to receive decision JSON automatically
• Poll the status endpoint for current decision and scores
• Verify X-Helios-Signature and route approvals to a review queue

Time to complete: ~12 minutes

Prerequisites

• SAGEA_API_KEY set in your environment as Bearer auth.
• Read Send your first API request to create a key.
• Read How Helios works to understand approved and review and declined states.
• A public HTTPS endpoint for callbacks, for example https://example.com/webhooks/helios.

Step 1: Register a callback URL

Set callback_url in the request or in the dashboard. Helios POSTs the full decision JSON to it when verification completes.

curl -X POST https://api.sagea.space/helios/kyc/v1 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -F front_image=@"front.jpg" \
  -F back_image=@"back.jpg" \
  -F liveness_video=@"liveness.mp4" \
  -F external_id="user_12345" \
  -F callback_url="https://example.com/webhooks/helios"

Step 2: Poll the status endpoint

curl https://api.sagea.space/helios/verifications/helios_vrf_9f3a2c1e \
  -H "Authorization: Bearer $SAGEA_API_KEY"

Step 3: Verify webhook signatures and queue reviews

Helios signs each callback with X-Helios-Signature. Verify it, then push review decisions into your analyst queue.

curl -X POST https://example.com/webhooks/helios \
  -H "Content-Type: application/json" \
  -H "X-Helios-Signature: test_signature" \
  -d '{"verification_id":"helios_vrf_9f3a2c1e","decision":"review"}'

Verify

A healthy flow returns HTTP 200 on status polls and HTTP 200 from your webhook receiver. If it fails, check below.

What's next

• Document-only checks
• Batch KYC at scale
• How Helios works