Skip to content

Webhook Quick Start

Get webhooks working in a few minutes: register your URL, copy the secret, and implement a simple endpoint.

In plain terms

You give Moveris a URL. Moveris sends the verification result to that URL when it's done. You verify the request is from Moveris using a secret, then process the result.

Prerequisites

  • A Moveris account and API key
  • A publicly reachable HTTPS endpoint

Required API key scopes

Webhook configuration requires an API key with: webhooks:read, webhooks:write. Keys with no scopes have full access. See Authentication.

Steps

1. Add your webhook URL

  1. Sign in to the Moveris Developer Portal.
  2. Go to API Keys → select your key → Configure Webhook.
  3. Enter your URL (e.g. https://your-app.com/api/moveris/webhook).
  4. Choose the model (e.g. mixed-30-v2).
  5. Click Save and copy the Webhook Secret immediately—it is shown only once.

2. Implement the endpoint

Your server must accept POST requests and verify the X-Webhook-Signature header:

import hmac
import hashlib

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

3. Process the payload

Webhook payloads are not wrapped in the API response envelope. The body is JSON with event, session_id, timestamp, and a data object containing the full verification result:

{
  "event": "verification.completed",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-27T15:26:42.123456Z",
  "data": {
    "verdict": "live",
    "confidence": 0.94,
    "real_score": 0.94,
    "score": 94.0,
    "type": "VERY HIGH",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "mixed-10-v2",
    "input_source": "rest_frames",
    "processing_ms": 845,
    "frames_processed": 10,
    "tenant_metadata": null,
    "warning": null,
    "created_at": "2026-03-27T15:26:42.123456Z"
  }
}
Field Type Description
event string Event type (verification.completed)
session_id string Session UUID that triggered the event
timestamp string (ISO 8601) When the event was emitted
data.verdict string live or fake
data.real_score float Raw liveness probability (0-1)
data.score float Percentage score (0-100)
data.type string Risk band: VERY LOW, LOW, MEDIUM, HIGH, VERY HIGH
data.model string Model alias used
data.input_source string rest_frames, rest_crops, or video_upload
data.processing_ms integer Server processing time in milliseconds
data.frames_processed integer Number of frames analyzed
data.tenant_metadata object | null Tenant metadata when applicable
data.warning string | null Warning message if any
data.created_at string (ISO 8601) When the verification was processed

Next Steps