Skip to main content

​
Available Library/SDK for Quick Integration

The Adhere Web SDK provides a seamless, secure way to verify user presence (Liveness) and match their identity against official documents. Our SDK handles the heavy lifting of frame capture, face extraction, secure transmission, and verification asynchronously.

​
Getting started

To initialize the SDK, you will need:
  • Public API Key - apiKey: Found in your Adhere Dashboard settings.
  • Configuration ID - clientID: The unique ID for your specific liveness workflow.

​
Installation

For web applications, install our library via NPM. 
npm i @smartcomply/web-sdk@latest

​
Implementation

Create a Session Before initializing the SDK, your server must request a short-lived sessionToken.
  • Base URL: https://adhere-api.smartcomply.com
  • Endpoint: POST {BASE_URL}/v1/sdk/sessions/create/
  • Header: Authorization: Api-Key <YOUR_API_KEY>
  • Body: {"client_id": "<YOUR_SDK_CONFIG_ID>"}
  • Content-Type: application/json
Response: 
{ "token": "4505e4b3-f92b-46e5-9008-a98eeaabb6e5" }
Initialize the SDK Pass the token received into the SDK constructor. Initialize the verification engine by calling the sdk.launch() method. This launches a secure overlay that guides the user through the liveness challenges (e.g., blinking, head rotation) and document upload. 
import AdhereSDK from "@smartcomply/web-sdk";

const sdk = new AdhereSDK({
  session: "4505e4b3-f92b-46e5-9008-a98eeaabb6e5",
  timeout: 15000, // can be undefined

  // callback Props
  onSuccess: (data) => {
    console.log("Verification submitted:", data);
  },

  onError: (error) => {
    console.error("Something went wrong: " + error.message);
  }

  onExpire: () => {
    console.error("Verification session expired");
  }
});

// launch SDK
document.getElementById("test-launch-btn").onclick = () => sdk.launch();

​
Callback Specifications

onSuccess(payload) Triggered when the session is successfully completed.
PropertyTypeDescription
dataSuccessDataTypeThe created liveness entry session.
statusInteger200
messageStringHuman-readable message
type SuccessDataType = {
  entryId: number;
  identifier: string;
  identifier_type: string;
  video_url: string;
  autoshot_url: string;
  document_url: string;
}
onError(error) Triggered during network failures, permission denials, or session expiration.
PropertyTypeDescription
errorErrorThe error object
codeStringUnique error code: e.g. AUTH_ERROR, TIMEOUT_ERROR, ENTRY_CREATION_ERROR, SUBMISSION_ERROR, or UNKNOWN_ERROR.
messageStringHuman-readable explanation of the error.

​
Webhook Integration

Since face matching involves complex asynchronous processing, the final result is sent to your server via a Webhook.

​
Payload Schema

When the verification is complete, Adhere will send a POST request to your configured Webhook URL. Sample JSON Payload 
{
  "event": "liveness.completed",
  "data": {
    "entry_id": 43,
    "status": "passed",
    "is_verified": true,
    "match_score": 0.31375,
    "metadata": {
      "user-agent": "",
      "ip_address": "192.168.0.1",
    }
  },
  "timestamp": "2026-02-17T02:13:58Z"
}

​
Field definitions

FieldDescriptionType
statusThe status of the session (passed, failed, expired).string
is_verifiedWhether we successfully matched the selfie to the ID.boolean
match_scoreThe “Distance” between faces. Lower is better. Facenet threshold is 0.40.float
entry_idUnique identifier for this verification record.String

​
Explaining the Match Score (Distance)

Match score is a measure of “how different” two faces are. It is represents the mathematical distance between the selfie and the ID. A lower score indicates a higher probability of a match. While our system flags is_verified: true for any score below 0.40, we recommend a manual audit for any scores falling in the Borderline range (0.40 - 0.50) to account for extreme lighting or age differences in documents.
Score RangeInterpretationAction Recommended
0.0 - 0.25Identical matchAuto-Approve
0.25 - 0.40Strong matchAuto-Approve
0.40 - 0.50Borderline matchManual Review
0.50+Different peopleReject

​
Security & Best Practices

​
Verify the Source - Webhook Signatures

To ensure that webhook requests are coming from Adhere, we include an X-Adhere-Signature in the header of every request. You should verify this signature before processing the data. Verification Steps
  • Retrieve your webhook_secret from the Adhere Dashboard.
  • Get the raw body of the POST request.
  • Compute the HMAC hex digest using the SHA256 hash function and your secret key.
  • Compare your computed signature with the one in the X-Adhere-Signature header.
Example (Node.js/Express) 
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-adhere-signature"];
  const secret = process.env.ADHERE_WEBHOOK_SECRET;

  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(req.body))
    .digest("hex");

  if (signature === computedSignature) {
    // Legit request
    res.status(200).send("Verified");
  } else {
    // Possible spoofing attempt
    res.status(401).send("Invalid Signature");
  }
});

​
Handle Retries

Our systems expect a 200 OK response. If your server is down, we will retry the notification 3 times with exponential backoff (10 minute cap) + jitter.