Skip to content

Webhook Overview

Webhooks let you receive Moveris verification results automatically. When a liveness check completes, Moveris sends an HTTP POST to your server—no polling needed.

In plain terms

Instead of repeatedly asking "is it done yet?", your server gets notified the moment a verification finishes. You receive the result (live or fake) and can update your database, trigger workflows, or notify users immediately.

Why Use Webhooks?

Approach How it works Best for
Polling Agent calls check_verification_status every 1–2 seconds until done Simple setups, one-off verifications
Webhook Moveris POSTs to your URL when verification completes Production, high throughput, MCP agents

Webhooks reduce latency and server load. The moment a user completes a verification, your endpoint receives the result. No repeated status checks.

Required API key scopes

Webhook configuration requires an API key with: - webhooks:read — List webhook configurations - webhooks:write — Create, update, delete webhook configs

Keys with no scopes have full access. See Authentication.

How It Works

  1. You register a webhook URL in the Developer Portal for your API key.
  2. When a verification completes or fails after validation (via MCP tools or API), Moveris may send an HTTP POST to your URL, depending on which events you subscribed to.
  3. The request includes headers (X-Webhook-Event, X-Webhook-Session, X-Webhook-Signature) and a JSON body (event, session_id, timestamp, data).
  4. You verify the signature using your webhook secret, then branch on event and process data.

Events

Event When
verification.completed A liveness verification finished with a live or fake verdict
verification.failed Processing failed after auth/validation (e.g. ML or video pipeline error); data describes the error—there is no verdict

In the Developer Portal, webhook delivery logs let you inspect each delivery attempt, filter by event and model, and open a detail view that includes the request_body sent to your endpoint.