Webhooks - Adhere by Smartcomply

In a nutshell: Webhooks allow you to set up a notification system that can be used to receive updates on certain requests made to the Adhere API.

Adhere uses webhooks to notify your application when specific events occur. This allows you to build automated workflows and integrate Adhere closely with your system.

Why use Webhooks?

Generally, when you make a request to an API endpoint, you expect to get a near-immediate response. However, some requests may take a long time to process. In order to prevent a timeout error, a pending response is returned. Since your records need to be updated with the final state of the request, you need to either:

Polling: Make a request for an update at regular intervals.
Webhooks: Listen to events by using a webhook URL.

We recommend using webhooks over polling. Webhooks are more efficient, reduce network overhead, and ensure your system is updated immediately when an event occurs.

Setup & Integration

To start receiving webhook notifications, follow these steps to configure your environment:

Configure Webhook URL

Provide the endpoint on your server where Adhere will send POST requests. This should be a publicly accessible URL.

Set Hash Key

A secret key used to sign the webhook payload. You must keep this secure and use it to verify that requests are coming from Adhere.

Save Configuration

Save your settings in the Adhere dashboard under the Integrations section.

There are two independent webhook channels, each with its own URL and its own signing secret:

Module events (transaction monitoring, KYC) go to the URL set under Integrations, and are signed with the Hash Key you set there.
Identity verification (liveness.completed, sent for every Web, Android and iOS SDK run) goes to the webhook URL set on your SDK Config, and is signed with that config’s own webhook secret. It is generated for you, not set by you.

Both use the same X-Adhere-Signature header and the same HMAC-SHA256 scheme described below.

Security & Verification

All webhook requests from Adhere include an X-Adhere-Signature header in the form sha256=<signature>, where the signature is the lowercase hex HMAC-SHA256 digest of the request body.

Verifying Signatures

To ensure that a webhook request is genuinely from Adhere, you should verify the signature before processing the payload.

Compute the HMAC over the raw request body bytes, exactly as received. Adhere signs a compact JSON serialisation with no whitespace between separators, so re-serialising a parsed payload produces different bytes and the signature will never match.

For liveness.completed, the signing key is your SDK Config’s webhook secret with the dashes removed — a 32-character hex string, not the dashed UUID form. The examples below strip them for you.

Getting your SDK Config’s webhook secret

The secret is generated for you when the SDK Config is created. Get it from the Adhere Dashboard: go to Settings → Integrations → SDK, open the menu on your config’s row and choose Integration. The secret is shown there with your Config ID, with a button to copy it. Treat it like a password. Anyone holding it can forge a validly signed webhook carrying fabricated verification results, so store it the way you store any other server-side credential and never ship it in client code.

import hmac
import hashlib
from flask import request, abort

def verify_webhook(request, hash_key):
    sig_header = request.headers.get("X-Adhere-Signature")
    if not sig_header:
        abort(401, "Missing signature")

    # The header format is "sha256=<hex digest>"
    _, _, received_sig = sig_header.partition("=")

    # Compute the HMAC SHA256 digest of the raw request body
    raw_body = request.get_data()
    expected_sig = hmac.new(
        hash_key.replace("-", "").encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(received_sig, expected_sig):
        abort(401, "Invalid signature")

const crypto = require('crypto');

// `req.rawBody` must be the unparsed body. With Express:
//   app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));
function verifyWebhook(req, hashKey) {
  const signature = req.headers['x-adhere-signature'];
  if (!signature) {
    throw new Error('Missing signature');
  }

  const receivedSig = signature.replace(/^sha256=/, '');
  const expected = crypto
    .createHmac('sha256', hashKey.replace(/-/g, ''))
    .update(req.rawBody)
    .digest('hex');

  const valid =
    receivedSig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(receivedSig, 'hex'), Buffer.from(expected, 'hex'));

  if (!valid) {
    throw new Error('Invalid signature');
  }
}

function verify_webhook($request_body, $hash_key, $received_sig) {
    $received_sig = preg_replace('/^sha256=/', '', $received_sig);
    $expected_sig = hash_hmac('sha256', $request_body, str_replace('-', '', $hash_key));

    if (!hash_equals($expected_sig, $received_sig)) {
        http_response_code(401);
        exit("Invalid signature");
    }
}

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"strings"
)

func verifyWebhook(w http.ResponseWriter, r *http.Request, hashKey string) bool {
	sigHeader := r.Header.Get("X-Adhere-Signature")
	if sigHeader == "" {
		return false
	}

	// Header format is "sha256=<hex digest>"
	parts := strings.SplitN(sigHeader, "=", 2)
	if len(parts) != 2 {
		return false
	}
	receivedSig := parts[1]

	body, _ := io.ReadAll(r.Body)
	h := hmac.New(sha256.New, []byte(strings.ReplaceAll(hashKey, "-", "")))
	h.Write(body)
	expectedSig := hex.EncodeToString(h.Sum(nil))

	return hmac.Equal([]byte(receivedSig), []byte(expectedSig))
}

using System.Security.Cryptography;
using System.Text;

public bool VerifyWebhook(string requestBody, string hashKey, string receivedSig)
{
    receivedSig = receivedSig.StartsWith("sha256=") ? receivedSig.Substring(7) : receivedSig;

    var keyBytes = Encoding.UTF8.GetBytes(hashKey.Replace("-", ""));
    var bodyBytes = Encoding.UTF8.GetBytes(requestBody);

    using (var hmac = new HMACSHA256(keyBytes))
    {
        var hashBytes = hmac.ComputeHash(bodyBytes);
        var expectedSig = Convert.ToHexString(hashBytes).ToLowerInvariant();

        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expectedSig),
            Encoding.UTF8.GetBytes(receivedSig));
    }
}

Always verify the X-Adhere-Signature header to prevent unauthorized requests from interacting with your server.

Event Payload Structure

Module events follow a consistent JSON structure:

Parameter	Type	Description
`success`	boolean	Indicates if the event was processed successfully.
`module`	string	The Adhere module that triggered the event (e.g., `transaction_monitoring`, `kyc`).
`event`	string	The specific event type.
`data`	object	The actual payload data (e.g., transaction details, KYC results).

Identity verification does not use this envelope. Its payload is flat, with the verification fields at the top level.

Supported Events

Transaction Monitoring

Module: transaction_monitoring

Events:

suspicious_transaction: Triggered when a transaction is processed and deemed suspicious.

{
  "data": {
    "id": 23,
    "is_internal_blacklisted": false,
    "is_blacklisted_by": null,
    "case_id": "#8N2ZI6",
    "case_sla": "2025-08-23T09:39:31.551479Z",
    "case_status": "open",
    "transaction_id": "9201634916397893719",
    "amount": 12345.0,
    "currency": "EUR",
    "transaction_type": "card",
    "account_type": "individual",
    "customer_name": "David Seaman",
    "customer_email": "davidseaman@example.com",
    "customer_ip_address": "192.168.0.8",
    "customer_location": "Yaba, LG",
    "origin_account_no": "4321567809",
    "origin_bank_code": "327",
    "transaction_description": "Payment for order #78901",
    "destination_account_no": "0123456789",
    "destination_bank_code": "723",
    "merchant_name": null,
    "merchant_location": null,
    "status": "suspicious",
    "card_bin": null,
    "card_last4": null,
    "bvn": "7890123456",
    "fraud_percent": null,
    "tag": [
      "1 rule(s) triggered"
    ],
    "sender_blacklisted": false,
    "receiver_blacklisted": false,
    "rules_flagged": [
      "Any transaction by an individual that exceeds an amount {a}"
    ],
    "additional_info": {},
    "date_created": "2025-08-20T09:39:31.425545Z",
    "date_updated": "2026-01-16T13:46:07.388489Z",
    "branch": 2
  },
  "event": "suspicious_transaction",
  "module": "transaction_monitoring",
  "success": true
}

Identity Verification

Sent by: every Web, Android and iOS SDK verification
Delivered to: the webhook URL on your SDK Config (not the Integrations URL)
Events:
- liveness.completed: fired once per verification, after face matching and, for document runs, OCR have finished.

This payload is flat — there is no success / module / data wrapper.

POST https://your-server.com/webhook
Content-Type: application/json
X-Adhere-Signature: sha256=<hmac-sha256-hex>

{
  "event": "liveness.completed",
  "verification_id": 42,
  "verification_type": "data_verification",
  "status": "passed",
  "failure_reason": null,
  "timestamp": "2026-08-08T10:15:00.000Z",
  "subject": {
    "identifier": "12345678901",
    "identifier_type": "National Identity Number (NIN)",
    "country": "nigeria"
  },
  "biometrics": {
    "liveness_verified": true,
    "face_match": {
      "attempted": true,
      "verified": true,
      "confidence_percentage": 70.0,
      "decision": "MATCH"
    },
    "selfie_url": "https://.../autoshot.jpg",
    "face_analysis": {
      "gender": "Female",
      "dominant_emotion": "neutral",
      "face_quality": {
        "face_detected": true,
        "face_confidence": 0.98,
        "blur_score": 142.3,
        "is_blurry": false
      }
    }
  },
  "activity": {
    "session_id": "da7623bd-9158-4b56-a9e4-4bccf3c0133f",
    "started_at": "2026-08-08T10:12:00.000Z",
    "submitted_at": "2026-08-08T10:14:30.000Z",
    "completed_at": "2026-08-08T10:15:00.000Z",
    "duration_seconds": 180
  },
  "request_context": {
    "ip": { "address": "102.67.1.66", "city": "Lagos", "country_code": "NG" },
    "device": { "user_agent": "Mozilla/5.0 ...", "type": "desktop", "os": "Windows" }
  },
  "customer_profile": {
    "first_name": "AMARA",
    "last_name": "OKAFOR",
    "other_name": null,
    "date_of_birth": "01-Jan-1997",
    "age": 29,
    "gender": "Female",
    "id_number": "12345678901",
    "serial_number": null,
    "occupation": null,
    "place_of_birth": null,
    "place_of_live": "...",
    "date_of_issue": null,
    "photo_url": null
  }
}

verification_type is data_verification or document_verification. For a document run the same top-level shape applies, with a document block (OCR fields plus a document-to-selfie face match) in place of customer_profile:

"document": {
  "status": "verified",
  "document_type": "passport",
  "is_expired": false,
  "first_name": "AMARA",
  "last_name": "OKAFOR",
  "date_of_birth": "1997-01-01",
  "age": 29,
  "gender": "Female",
  "nationality": "NGA",
  "document_number": "A12345678",
  "expiry_date": "2030-06-15",
  "issue_date": "2020-06-15",
  "issuing_authority": "...",
  "document_url": "https://.../document.jpg",
  "document_back_url": null,
  "face_match": {
    "attempted": true,
    "verified": true,
    "confidence_percentage": 55.0,
    "reason": null,
    "selfie_url": "https://.../autoshot.jpg",
    "document_face_url": "https://.../document_face.jpg"
  }
}

document also carries place_of_birth, place_of_issue, address, district, division, location, sub_location, serial_number, and barcode_number — null unless the specific document type carries that field. face_match.reason is populated with a user-facing explanation when verified is false or the match was skipped.

face_match.decision ("MATCH", "NO_MATCH", or "REJECTED") is what verified is actually derived from — read decision rather than comparing confidence_percentage against a threshold of your own, since our internal match threshold isn’t part of this payload and may change over time. "REJECTED" means liveness/anti-spoofing failed before any comparison ran, so confidence_percentage can be absent or 0 alongside verified: false for a reason unrelated to how similar the faces looked.

status: "passed" means the check ran to completion — not that the person matched. A face mismatch, a low confidence score, or an expired document still reports status: "passed", with the real outcome recorded in biometrics.face_match.verified (and document.is_expired for document verification). status: "failed" is reserved for cases where the check itself could not run: a service error, no selfie captured, or a government database rejection. Never gate access on status alone — always check face_match.verified.

verification_id matches the entryId returned by the SDK’s completion callback.

Testing Locally

Before deploying to production, we recommend testing your webhook implementation locally.

Use ngrok: Use ngrok to create a secure tunnel to your local server.
Set Webhook URL: Update your Adhere dashboard with the ngrok URL (e.g., https://your-subdomain.ngrok-free.app/webhooks).
Inspect Requests: Use the ngrok dashboard or Webhook.site to inspect the payloads and headers sent by Adhere.

Best Practices

Acknowledge Immediately: Your server should return a 200 OK response as quickly as possible. Heavy processing should be handled asynchronously using a task queue.
Handle Retries: Adhere will retry failed webhook deliveries (non-2xx responses) up to 3 times, with an exponential backoff that caps at 10 minutes.
Use Idempotency: Ensure your system can handle the same webhook multiple times safely. There is no separate delivery ID — de-duplicate on the resource identifier in the payload (verification_id for liveness.completed, data.id for module events).

If your server does not return a 2xx response, Adhere will consider the delivery as failed and will attempt to retry.

​Why use Webhooks?

​Setup & Integration

​Security & Verification

​Verifying Signatures

​Getting your SDK Config’s webhook secret

​Event Payload Structure

​Supported Events

​Transaction Monitoring

​Identity Verification

​Testing Locally

​Best Practices

Why use Webhooks?

Setup & Integration

Security & Verification

Verifying Signatures

Getting your SDK Config’s webhook secret

Event Payload Structure

Supported Events

Transaction Monitoring

Identity Verification

Testing Locally

Best Practices