const res = await fetch('https://api.liveness.io/v1/sessions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.LIVENESS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ challenge_count: 5 }),
})
const { session_id, hosted_url } = await res.json()
// → send session_id / hosted_url to the client

import { LivenessClient } from '@liveness/sdk'

const client = new LivenessClient({ apiUrl: 'https://api.liveness.io' })
const result = await client.run(sessionId, videoElement, apiKey)
// result: { passed: true, score: 0.968, sessionId: '...' }

curl https://api.liveness.io/v1/sessions \
  -H "X-API-Key: lv_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"challenge_count": 5}'

{
  "session_id":        "a1b2c3d4-...",
  "challenges":        ["BLINK", "SMILE", "TURN_LEFT", "OPEN_MOUTH", "RAISE_EYEBROWS"],
  "current_challenge": "BLINK",
  "challenge_index":   0,
  "total_challenges":  5,
  "expires_in_seconds": 300,
  "hosted_url":        "https://app.liveness.io/check?s=a1b2c3d4-..."
}

{
  "challenge_passed": false,
  "face_detected":    true,
  "session_status":   "pending",
  "current_challenge": "BLINK",
  "confidence":       0.12,
  "message":          "Challenge not passed yet — keep trying"
}

{
  "challenge_passed": true,
  "session_status":   "pending",
  "next_challenge":   "SMILE",
  "challenge_index":  1,
  "total_challenges": 5,
  "message":          "Great! Now: SMILE"
}

{
  "challenge_passed":  true,
  "session_status":    "passed",
  "score":             0.968,
  "liveness_verified": true,
  "message":           "Liveness verified successfully"
}

{
  "challenge_passed": false,
  "session_status":   "failed",
  "reason":           "spoof_detected",
  "message":          "Liveness check failed — please use a live camera"
}

import { WebView } from 'react-native-webview'
import { useRef } from 'react'

export default function LivenessScreen({ hostedUrl, onResult }) {
  const ref = useRef(null)

  return (
    <WebView
      ref={ref}
      source={{ uri: hostedUrl }}
      onMessage={(e) => {
        const { type, passed, score, session_id } = JSON.parse(e.nativeEvent.data)
        if (type === 'liveness_result') {
          onResult({ passed, score, session_id })
        }
      }}
    />
  )
}

WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel('LivenessResult', onMessageReceived: (msg) {
    final data = jsonDecode(msg.message);
    // data['passed'], data['score'], data['session_id']
  })
  ..loadRequest(Uri.parse(hostedUrl));

{
  "type":       "liveness_result",
  "passed":     true,
  "score":      0.968,
  "session_id": "a1b2c3d4-..."
}

{
  "event":      "session.completed",
  "session_id": "a1b2c3d4-...",
  "passed":     true,
  "score":      0.968,
  "reason":     null,
  "timestamp":  "2026-06-01T12:00:00.000Z"
}

app.post('/webhooks/liveness', express.json(), (req, res) => {
  const { event, session_id, passed, score } = req.body

  if (event === 'session.completed') {
    if (passed) {
      // unlock the user's account, continue onboarding flow, etc.
      console.log(`Session ${session_id} passed with score ${score}`)
    } else {
      console.log(`Session ${session_id} failed`)
    }
  }

  res.sendStatus(200)
})

npm install @liveness/sdk

import { LivenessClient } from '@liveness/sdk'

const client = new LivenessClient({
  apiUrl: 'https://api.liveness.io',
})

// videoElement is an HTMLVideoElement already in the DOM
const result = await client.run(sessionId, videoElement, apiKey)

// result shape:
// { passed: boolean, score: number, sessionId: string }

if (result.passed) {
  console.log('Liveness score:', result.score) // 0.0 – 1.0
}

import LivenessWidget from '@/components/LivenessWidget'

<LivenessWidget
  apiKey={sessionApiKey}
  challengeCount={5}
  onComplete={({ passed, score }) => {
    console.log('done', passed, score)
  }}
/>

POST /webhooks/liveness HTTP/1.1
Content-Type: application/json
X-Liveness-Signature: sha256=a3f1c8...

const crypto = require('crypto')

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  // timingSafeEqual prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  )
}

// Use express.raw() so req.body is a Buffer (unparsed)
app.post('/webhooks/liveness', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-liveness-signature']
  if (!sig || !verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.sendStatus(401)
  }
  const { event, passed, score, session_id } = JSON.parse(req.body)
  if (event === 'session.completed' && passed) {
    // unlock account, continue onboarding, etc.
  }
  res.sendStatus(200)
})

import hmac, hashlib, os

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# FastAPI
@app.post("/webhooks/liveness")
async def webhook(request: Request):
    raw = await request.body()
    sig = request.headers.get("x-liveness-signature", "")
    if not verify_webhook(raw, sig, os.environ["WEBHOOK_SECRET"]):
        raise HTTPException(status_code=401)
    payload = json.loads(raw)
    # handle payload …
    return {"ok": True}

{ "error": "Session is already 'passed'" }