Production Checklist

Use this checklist before switching your FaceSign integration from the dev environment to production. Each step addresses a category that commonly causes issues in live deployments.

Deployment

# Development
FACESIGN_API_KEY=sk_test_abc123...

# Production
FACESIGN_API_KEY=sk_prod_xyz789...

cd my-nextjs-demo
printf "sk_prod_your_key_here" | npx vercel env add FACESIGN_API_KEY production
npx vercel --prod --yes

cd my-demo
npx vercel --prod --yes

npx vercel env rm FACESIGN_API_KEY production --yes
printf "sk_prod_new_key" | npx vercel env add FACESIGN_API_KEY production

Flow correctness checklist

These rules are load-bearing. Violating them causes the avatar to hallucinate, loop, double-speak, or fail silently. Every rule is the result of real debugging time across real integrations.

• No conditional logic in single prompts -- use structural branching only
• No "default" fallback outcomes on conversation nodes
• doesNotRequireReply only on the final closing node
• One question per conversation node
• No self-loops: no outcome's targetNodeId equals its own node's id
• The greeting is long enough for video accumulation (5 seconds or more of avatar speech)
• All liveness and recognition outcomes route forward, never to end or an error state
• Conversation prompts are authored in English — Say: for verbatim wording the avatar must speak, descriptive phrasing when paraphrase is acceptable. The runtime translates both into the session language.

Localization

Every FaceSign session runs through the same translation pipeline — there is no separate "English-only" mode. Whenever you expect users in more than one language, make sure the surrounding configuration matches:

• langs whitelist set on session.create to the languages you want to support
• defaultLang set on session.create so users whose browser language isn't in langs fall back predictably
• UI strings on your landing and recap pages cover every language in langs
• Currency, date, and number formats rendered through locale-aware APIs (Intl.NumberFormat, Intl.DateTimeFormat)
• Smoke-tested in each target language by setting the browser's primary language accordingly

Webhook validation

import crypto from 'node:crypto'

function verifyFacesignSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('='))
  )
  if (!parts.t || !parts.v1) return false
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`, 'utf8')
    .digest('hex')
  try {
    return crypto.timingSafeEqual(
      Buffer.from(parts.v1, 'hex'),
      Buffer.from(expected, 'hex')
    )
  } catch {
    return false
  }
}

export async function POST(req) {
  // 1. Verify the HMAC signature against the raw body before
  //    trusting anything in the event.
  const rawBody = await req.text()
  const signature = req.headers.get('x-facesign-signature')
  if (!verifyFacesignSignature(rawBody, signature, process.env.FACESIGN_WEBHOOK_SECRET)) {
    return new Response('Invalid signature', { status: 401 })
  }

  const event = JSON.parse(rawBody)

  // 2. Verify the session belongs to you.
  const session = await db.sessions.find(event.sessionId)
  if (!session) {
    return Response.json({ error: 'Unknown session' }, { status: 400 })
  }

  // 3. Deduplicate on the event id.
  if (await db.webhookEvents.exists(event.id)) {
    return Response.json({ received: true })
  }

  // 4. Acknowledge immediately; do slow work on a queue.
  await queue.enqueue('facesign-webhook', event)
  await db.webhookEvents.insert({ id: event.id })
  return Response.json({ received: true })
}

Monitoring and logging

Retry logic

Design your integration to handle transient failures:

• API calls -- Retry on 5xx responses and network timeouts. Use exponential backoff with jitter (e.g., 1s, 2s, 4s + random).
• Media downloads -- If a media URL download fails, re-fetch the session to get a fresh URL before the expiry window closes.
• Webhook processing -- If your internal processing fails after acknowledging a webhook, enqueue the event for retry in your own job queue.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(url, options)
      if (res.status >= 500 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500
        await new Promise(r => setTimeout(r, delay))
        continue
      }
      return res
    } catch (err) {
      if (attempt === maxRetries) throw err
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500
      await new Promise(r => setTimeout(r, delay))
    }
  }
}

Security review

Before going live, verify:

• API keys are stored in environment variables or a secrets manager, not in code
• Client secrets are generated server-side and never exposed alongside your API key
• Webhook endpoints use HTTPS only
• Media files are downloaded to secure storage with access controls
• CORS is configured to allow only your application's origin
• Session data containing biometric information is handled according to your data retention policy

Compliance

• Privacy and data retention settings match your obligations (GDPR, CCPA, BIPA as applicable)
• Branding, copy, and the recap page match your product voice
• Tested on desktop and mobile on the platforms you target

Remove test data

Clean up before launch:

• Delete test sessions from your database that reference sandbox session IDs
• Remove any hardcoded sk_test_ keys from configuration files
• Clear cached sandbox responses from your development environment
• Verify that your webhook endpoint is registered with the production URL, not a dev/ngrok URL

Quick reference

Both environments share the same API base URL (https://api.facesign.ai) and session host (https://session.facesign.ai). The API key prefix is what routes your requests into the right environment.

Next steps