Webhooks

The OneKYC webhook system delivers verification event notifications to your URL in real time. KYC events (sessions, verification, steps, documents, links, etc.) and KYB events (business verification) are both supported. You select the event types when configuring the endpoint in the admin panel.

Key properties:

• KYC events (sessions, verification, steps, documents, links, etc.) and KYB events (see KYB webhooks)

• HMAC-SHA256 signing for delivery integrity

• Automatic retries with exponential backoff (up to 5 attempts)

• SHA-256 idempotency keys to prevent duplicate processing

• Delivery log and metrics in the admin panel

You configure webhooks in the admin panel: enter your server URL, select event types (or all types), and save. OneKYC sends signed POST requests for every event.

Configuration

In the Webhooks section of the admin panel, add your server URL, select the event types (or all types), and save. When the endpoint is created, the system generates a secret (with the whsec_ prefix) for signature verification. The secret is shown once — store it in a secure vault.

Event types

KYC events are grouped into the categories below. KYB events (the KYB events category in the admin panel) are documented in KYB webhooks.

Sessions (5 events)

Event	Description
session.created	A new verification session was created
session.started	The session was started (the user began verification)
session.completed	The session is complete — a terminal event, sent only after the final decision (automatic or by a manual review operator)
session.expired	The session expired
session.cancelled	The session was cancelled

Verification (6 events)

Event	Description
verification.approved	Verification approved
verification.declined	Verification declined
verification.needs_review	Verification routed to manual review by an operator (not a terminal state)
verification.ocr.corrected	OCR data was corrected by an operator
verification.resubmit_requested	A reviewer requested step resubmission (Manual Review Resubmit)
verification.resubmit_fulfilled	The applicant resubmitted the requested step

Event order for sessions with manual review

If a session needs manual review, events are sent in the following order:

1. verification.needs_review — sent right after automated checks finish with a "needs review" decision, or when an operator manually sends a terminal session back to review. session.completed is not sent at this point — the session is not finalised yet.

2. verification.approved or verification.declined — after the operator's final decision.

3. session.completed — sent immediately after verification.approved / verification.declined. The two events are sent as one chain.

If you only subscribe to session.completed, you receive that event exactly once — when the session is finalised. You do not see the intermediate "in review" state; subscribe to verification.needs_review for that.

For sessions without manual review (automatic approval/rejection), the event order is: verification.approved / verification.declined → session.completed.

session.completed is final for the customer-facing webhook cycle. Internally, a reviewer can later send a completed session back to review or request a resubmit; those operator actions emit verification.needs_review or resubmit events and do not replay the original session.completed until a new final decision is made.

Steps (5 events)

Event	Description
step.started	A verification step started
step.completed	A verification step completed
step.failed	The step finished with an error
step.skipped	The step was skipped because an upstream dependency did not pass
step.retried	The step is retried

Documents (1 event)

Event	Description
document.uploaded	A document was uploaded

AML screening (3 events)

Event	Description
aml.screening_completed	AML screening completed
aml.hit_found	A match against an AML watchlist was found
aml.cleared	AML screening completed with no matches

Verification links (4 events)

Event	Description
link.created	The verification link was created
link.consumed	The link was consumed
link.expired	The link expired
link.revoked	The link was revoked

Request format and signature

OneKYC sends a POST request with a JSON body to your URL. Every request carries the following headers:

Header	Description
Content-Type	application/json
X-Onekyc-Signature	Signature in the form t=<timestamp>,v1=<signature>
X-Onekyc-Event-Type	Event type (for example, session.created)
X-Onekyc-Event-Id	Event UUID
X-Onekyc-Timestamp	Unix timestamp of the send
User-Agent	OneKYC-Webhook/1.0

HTTP header names are case-insensitive (RFC 7230 §3.2). On the receiving side, use case-insensitive comparison (most HTTP frameworks do this automatically).

Verifying the signature

To verify a webhook's authenticity:

1. Extract t (timestamp) and v1 (signature) from the X-Onekyc-Signature header.

2. Build the signed string: {timestamp}.{raw_body} (the numeric value from t, a literal dot, then the raw request body).

3. Compute HMAC-SHA256 using your webhook secret (whsec_...).

4. Compare the result with v1 from the header (use a constant-time comparison).

5. Confirm that the timestamp is within the allowed window (5 minutes is recommended).

Replay protection: reject requests where |now - X-Onekyc-Timestamp| > 300 seconds (5 minutes). Additionally, use the X-Onekyc-Event-Id header (UUID) for deduplication — store processed event IDs and ignore duplicate deliveries.

When the secret is rotated, the header also carries v2=<signature> — the signature with the new key. Both keys are valid during the grace period.

Signature verification examples

Node.js:

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  // Extract timestamp and signature from the header
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
  const v1Signature = parts.find(p => p.startsWith('v1=')).split('=')[1];

  // Verify the timestamp is fresh (≤ 5 minutes old)
  const maxAgeSeconds = 300; // 5 minutes
  const currentTime = Math.floor(Date.now() / 1000);
  if (currentTime - parseInt(timestamp) > maxAgeSeconds) {
    throw new Error('Webhook timestamp is too old');
  }

  // Build the signed string: timestamp.raw_body
  const signedPayload = `${timestamp}.${rawBody}`;

  // Compute HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time compare
  if (!crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(v1Signature)
  )) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

Go:

import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "errors"
    "fmt"
    "strconv"
    "strings"
    "time"
)

func verifyWebhookSignature(rawBody []byte, signature, secret string) error {
    // Extract timestamp and signature from the header
    parts := strings.Split(signature, ",")
    var timestamp, v1Signature string

    for _, part := range parts {
        if strings.HasPrefix(part, "t=") {
            timestamp = strings.TrimPrefix(part, "t=")
        } else if strings.HasPrefix(part, "v1=") {
            v1Signature = strings.TrimPrefix(part, "v1=")
        }
    }

    if timestamp == "" || v1Signature == "" {
        return errors.New("invalid signature format")
    }

    // Verify the timestamp is fresh (≤ 5 minutes old)
    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return fmt.Errorf("invalid timestamp: %w", err)
    }

    maxAge := int64(300) // 5 minutes
    if time.Now().Unix()-ts > maxAge {
        return errors.New("webhook timestamp is too old")
    }

    // Build the signed string: timestamp.raw_body
    signedPayload := fmt.Sprintf("%s.%s", timestamp, rawBody)

    // Compute HMAC-SHA256
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signedPayload))
    expectedSignature := hex.EncodeToString(mac.Sum(nil))

    // Constant-time compare
    if subtle.ConstantTimeCompare(
        []byte(expectedSignature),
        []byte(v1Signature),
    ) != 1 {
        return errors.New("invalid webhook signature")
    }

    return nil
}

Payload format

Every event uses a single envelope format:

{
  "id": "evt_uuid",
  "type": "session.created",
  "api_version": "2026-02-01",
  "created_at": "2026-02-01T12:00:00Z",
  "tenant_id": "uuid",
  "environment": "production",
  "idempotency_key": "unique_key",
  "data": { ... }
}

The data field's contents depend on the event type (session, verification, step, document, link, etc.).

Retry policy

If delivery fails (the response is not 2xx), the system performs up to 5 total delivery attempts with exponential backoff (base delay 5 seconds, doubled on each retry, maximum interval 24 hours, with ±20% random jitter to spread the load). After all attempts are exhausted, the event is moved to the dead-letter queue (DLQ).

To acknowledge successful delivery, your server must respond with HTTP 2xx.

Idempotency key (idempotency_key): generated from a SHA-256 hash of the logical event identity and intended for receiver-side deduplication. The value is a 32-character hexadecimal string.

Example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Some session decision payloads may include optional enrichment fields when source data is available: applicant.details, applicant.localized, media_files, decision_reasons, and custom_steps. These fields are additive; webhook consumers should ignore fields they do not use.

Event payload examples

Session events (session.*)

Every session event contains a flat data structure with session info. Terminal KYC events such as session.completed also include the enriched applicant and verifications blocks. If the flow contains phone or email OTP steps, the verified values are included as data.applicant.phone and data.applicant.email.

The top-level result field is the source of truth for the final session decision. The verifications array may include historical retry attempts for a check. Each verification item includes attempt_number and is_current when available; use is_current: true as the current per-check result. For example, if document liveness failed on attempt 1 and passed on attempt 2, the terminal approved payload may contain both rows, with only the attempt 2 row marked as current.

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "session.completed",
  "api_version": "2026-02-01",
  "created_at": "2026-02-11T12:00:00Z",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "production",
  "idempotency_key": "example-idempotency-key",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "flow_id": "550e8400-e29b-41d4-a716-446655440003",
    "flow_version": 1,
    "external_id": "user_12345",
    "status": "completed",
    "created_at": "2026-02-11T10:00:00Z",
    "started_at": "2026-02-11T10:05:00Z",
    "completed_at": "2026-02-11T12:00:00Z",
    "expires_at": "2026-02-12T10:00:00Z",
    "steps_completed": 5,
    "result": "approved",
    "applicant": {
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "JOHN DOE",
      "document_number": "AB1234567",
      "document_type": "passport",
      "date_of_birth": "1990-01-15",
      "phone": "[phone]",
      "email": "[e-mail]"
    },
    "verifications": [
      {
        "type": "document_ocr",
        "step_id": "550e8400-e29b-41d4-a716-446655440010",
        "attempt_number": 1,
        "is_current": true,
        "status": "passed",
        "score": 0.95,
        "ocr": {
          "document_number": "AB1234567",
          "full_name": "JOHN DOE",
          "first_name": "JOHN",
          "last_name": "DOE",
          "date_of_birth": "1990-01-15",
          "issue_date": "2020-01-15",
          "expiry_date": "2030-01-15",
          "issuing_country": "USA",
          "document_type": "passport",
          "localized": {
            "English": {
              "Full Name": "JOHN DOE"
            }
          }
        }
      },
      {
        "type": "document_liveness",
        "step_id": "550e8400-e29b-41d4-a716-446655440010",
        "attempt_number": 2,
        "is_current": true,
        "status": "passed",
        "score": 0.96,
        "doc_liveness": {
          "is_real": true,
          "score": 0.96
        }
      }
    ]
  }
}

The full session field schema is in the API reference (Swagger / OpenAPI).

Verification events (verification.*)

Verification events contain full session info, applicant data extracted from the document, and the results of every check.

verification.approved:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "flow_id": "550e8400-e29b-41d4-a716-446655440003",
    "flow_version": 1,
    "external_id": "user_12345",
    "status": "completed",
    "result": "approved",
    "created_at": "2026-02-11T10:00:00Z",
    "started_at": "2026-02-11T10:01:00Z",
    "completed_at": "2026-02-11T12:00:00Z",
    "expires_at": "2026-02-12T10:00:00Z",
    "steps_completed": 5,
    "applicant": {
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "middle_name": "Michael",
      "gender": "M",
      "nationality": "USA",
      "issuing_country": "USA",
      "document_number": "AB1234567",
      "document_type": "passport",
      "date_of_birth": "1990-01-15",
      "date_of_expiry": "2030-01-15",
      "date_of_issue": "2020-01-15",
      "phone": "[phone]",
      "email": "[e-mail]"
    },
    "verifications": [
      {
        "type": "document_ocr",
        "step_id": "550e8400-e29b-41d4-a716-446655440010",
        "attempt_number": 1,
        "is_current": true,
        "status": "passed",
        "score": 0.95,
        "ocr": {
          "document_number": "AB1234567",
          "full_name": "JOHN DOE",
          "first_name": "JOHN",
          "last_name": "DOE",
          "date_of_birth": "1990-01-15",
          "nationality": "USA",
          "gender": "M",
          "issue_date": "2020-01-15",
          "expiry_date": "2030-01-15",
          "issuing_country": "USA",
          "issuing_authority": "U.S. Department of State",
          "document_type": "passport",
          "mrz_type": "TD3"
        }
      },
      {
        "type": "document_liveness",
        "step_id": "550e8400-e29b-41d4-a716-446655440010",
        "attempt_number": 2,
        "is_current": true,
        "status": "passed",
        "score": 0.96,
        "doc_liveness": {
          "is_real": true,
          "score": 0.96,
          "status": "Ok"
        }
      },
      {
        "type": "face_liveness",
        "step_id": "550e8400-e29b-41d4-a716-446655440011",
        "attempt_number": 2,
        "is_current": true,
        "status": "passed",
        "score": 0.97,
        "face_liveness": {
          "is_live": true,
          "score": 0.97,
          "faces": [
            {
              "x1": 80.0, "y1": 60.0, "x2": 220.0, "y2": 260.0,
              "yaw": 2.3, "pitch": -1.1, "roll": 0.5,
              "left_eye_closed": 0.03, "right_eye_closed": 0.04,
              "state": { "is_front": true, "quality": "High", "luminance": "Normal", "result": "Real" }
            }
          ]
        }
      },
      {
        "type": "face_match",
        "status": "passed",
        "score": 0.94,
        "face_match": {
          "score": 0.94,
          "is_match": true,
          "threshold": 0.7,
          "faces1": [
            {
              "x1": 80.0, "y1": 60.0, "x2": 220.0, "y2": 260.0,
              "yaw": 2.3, "pitch": -1.1, "roll": 0.5,
              "left_eye_closed": 0.03, "right_eye_closed": 0.04,
              "state": { "is_front": true, "quality": "High", "luminance": "Normal", "result": "Real" }
            }
          ],
          "faces2": [
            {
              "x1": 80.0, "y1": 60.0, "x2": 220.0, "y2": 260.0,
              "yaw": 2.3, "pitch": -1.1, "roll": 0.5,
              "left_eye_closed": 0.03, "right_eye_closed": 0.04,
              "state": { "is_front": true, "quality": "High", "luminance": "Normal", "result": "Real" }
            }
          ]
        }
      },
      {
        "type": "aml_screening",
        "status": "passed",
        "score": 0.9
      },
      {
        "type": "proof_of_address",
        "status": "passed",
        "score": 0.93,
        "proof_of_address": {
          "decision": "approved",
          "route": "gps_document",
          "reason_codes": ["gps_country_match", "document_address_match"],
          "applicant_message_code": "poa_approved",
          "reviewer_summary": "GPS, IP, and document evidence match the configured address policy.",
          "address_country": "USA",
          "address_city": "New York",
          "address_postal_code": "10001",
          "gps_accuracy_meters": 18.5,
          "ip_country": "USA",
          "ip_expected": "USA",
          "fingerprint_state": "consistent",
          "document_available": true,
          "document_category": "utility",
          "document_subtype": "utility_bill",
          "document_country": "USA"
        }
      }
    ]
  }
}

verification.declined:

{
  "data": {
    "session_id": "...",
    "result": "declined",
    "applicant": { "first_name": "Jane", "last_name": "Doe", "document_number": "CD9876543", "document_type": "passport" },
    "verifications": [
      {
        "type": "document_ocr",
        "status": "failed",
        "score": 0.95,
        "rejection_reasons": ["document_expired"],
        "ocr": {
          "document_number": "CD9876543",
          "first_name": "JANE",
          "last_name": "DOE",
          "date_of_birth": "1990-05-15",
          "expiry_date": "2020-01-01",
          "issuing_country": "USA",
          "document_type": "passport"
        }
      }
    ]
  }
}

verification.needs_review:

{
  "data": {
    "session_id": "...",
    "result": "review",
    "applicant": { "first_name": "Alice", "last_name": "Smith", "document_number": "EF5551234", "document_type": "passport" },
    "verifications": [
      {
        "type": "document_ocr",
        "status": "passed",
        "score": 0.91,
        "ocr": {
          "document_number": "EF5551234",
          "first_name": "ALICE",
          "last_name": "SMITH",
          "date_of_birth": "1985-03-20",
          "expiry_date": "2030-03-19",
          "issuing_country": "USA",
          "document_type": "passport"
        }
      },
      {
        "type": "face_match",
        "status": "review",
        "score": 0.76,
        "face_match": {
          "score": 0.76,
          "is_match": false,
          "threshold": 0.7,
          "faces1": [
            {
              "x1": 80.0, "y1": 60.0, "x2": 220.0, "y2": 260.0,
              "yaw": 2.3, "pitch": -1.1, "roll": 0.5,
              "left_eye_closed": 0.03, "right_eye_closed": 0.04,
              "state": { "is_front": true, "quality": "High", "luminance": "Normal", "result": "Real" }
            }
          ],
          "faces2": [
            {
              "x1": 80.0, "y1": 60.0, "x2": 220.0, "y2": 260.0,
              "yaw": 2.3, "pitch": -1.1, "roll": 0.5,
              "left_eye_closed": 0.03, "right_eye_closed": 0.04,
              "state": { "is_front": true, "quality": "High", "luminance": "Normal", "result": "Real" }
            }
          ]
        }
      },
      {
        "type": "proof_of_address",
        "status": "review",
        "score": 0.62,
        "proof_of_address": {
          "decision": "needs_review",
          "route": "document",
          "reason_codes": ["document_review_required"],
          "applicant_message_code": "poa_review_required",
          "reviewer_summary": "Document address was extracted but needs operator confirmation.",
          "address_country": "USA",
          "address_city": "Austin",
          "address_postal_code": "78701",
          "ip_country": "USA",
          "document_available": true,
          "document_category": "bank",
          "document_subtype": "bank_statement",
          "document_ocr_confidence_bucket": "medium",
          "document_ocr_degraded": false,
          "document_country": "USA"
        }
      }
    ]
  }
}

The full field schema with types, formats, and descriptions is in the API reference (Swagger / OpenAPI).

Step events (step.*)

Step events carry information about the execution of a single verification step:

{
  "type": "step.completed",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "step_id": "550e8400-e29b-41d4-a716-446655440010",
    "step_key": "document_capture",
    "step_type": "document",
    "step_name": "Upload Document",
    "execution_id": "550e8400-e29b-41d4-a716-446655440020",
    "attempt_number": 1,
    "status": "completed",
    "output": {
      "document_type": "passport",
      "storage_key": "documents/tenant_123/session_456/document.jpg"
    }
  }
}

Extra fields for step.failed:

Field	Description
error_code	Error code
error_message	Error description
max_attempts	Maximum allowed number of attempts (lets you tell whether this was the last attempt)

Extra fields for step.retried:

Field	Description
max_attempts	Maximum allowed number of attempts

Document events (document.*)

document.uploaded:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "step_id": "step_document_capture",
    "storage_key": "documents/tenant_123/session_456/document.jpg"
  }
}

Intermediate OCR / liveness / face-match / AML-screening / proof-of-address events are NOT delivered as separate webhook events. Their results are included in the verification.approved / verification.declined / verification.needs_review payload (the verifications array). Proof-of-address payloads include the redacted summary only; raw GPS coordinates and storage keys are not sent. See the examples above.

AML screening events (aml.*)

aml.screening_completed:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "match_found": false,
    "risk_score": 15.2,
    "decision": "approve",
    "match_severity": ""
  }
}

aml.hit_found:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "risk_score": 85.5,
    "decision": "review",
    "match_severity": "high"
  }
}

aml.cleared:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "risk_score": 5.0
  }
}

aml.enrichment field (Kontur.Focus)

Status: Generally available since 2026-04-24. Toggled at the AML-screening step level via the enable_focus_enrichment flag in the flow configuration (default true).

After the primary AML screening against Kontur.Compliance lists (sanctions, terrorists, PEP, bankruptcy, etc.), an extra enrichment stage runs through Kontur.Focus API. This stage augments the applicant decision with data from 13 Focus endpoints and produces a merged decision tagged with the source.

Enrichment results are included in the aml.screening_completed payload as an enrichment object:

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "match_found": true,
    "risk_score": 78.4,
    "decision": "review",
    "match_severity": "high",
    "enrichment": {
      "inn": "771234567890",
      "inn_source": "ocr",
      "inn_confidence": 0.92,
      "compliance_decision": "review",
      "compliance_match_count": 2,
      "merged_decision": "review",
      "merged_matches_count": 4,
      "merged_risk_score": 78.4,
      "hard_block_reason": null,
      "enrichment_status": "completed",
      "enrichment_completed_at": "2026-04-24T10:15:30Z",
      "call_statuses": {
        "passport_check": "completed",
        "sanctioned_persons": "completed",
        "pep_search": "completed",
        "person_bankruptcy": "completed",
        "person_affiliates": "completed",
        "smz": "skipped",
        "fssp": "skipped_no_inn",
        "general_court_cases": "completed"
      },
      "focus_passport": { "...": "see below" },
      "focus_sanctions": { "...": "see below" },
      "focus_pep": { "...": "see below" },
      "focus_person_bankruptcy": { "...": "see below" },
      "focus_affiliates": { "...": "see below" },
      "focus_smz_status": { "...": "see below" },
      "focus_fssp_summary": { "...": "see below" },
      "focus_court_summary": { "...": "see below" }
    }
  }
}

Enrichment fields:

Field	Type	Description
inn	string	Applicant's INN discovered by the pipeline (source listed in inn_source)
inn_source	string	INN source: ocr / compliance / focus_search / focus_affiliates / manual
inn_confidence	number	Confidence in the discovered INN (0.00–1.00)
compliance_decision	string	Kontur.Compliance decision before merging with Focus: approve / decline / review
compliance_match_count	int	Number of Compliance list matches
merged_decision	string	Final merged decision
merged_matches_count	int	Total number of matches (Compliance + Focus)
merged_risk_score	number	Final risk score (0.000–1.000 in DB, normalised to 0–100 in payload)
hard_block_reason	string | null	Reason for hard block (see below)
enrichment_status	string	pending / running / completed / failed
enrichment_completed_at	string (RFC3339)	When enrichment finished
call_statuses	object	Status of each Focus call: completed / error / skipped / skipped_no_inn

focus_passport field — Focus-side passport check:

{
  "checked_at": "2026-04-24T10:15:00Z",
  "valid": true,
  "source": "focus.checkPassport"
}

Source: the checkPassport Focus API endpoint. Used as a second source for passport verification in addition to the built-in passport_check of the verification step.

focus_sanctions field — hits against Focus sanctions lists:

{
  "items": [
    {
      "list_name": "EU consolidated list",
      "matched_name": "IVANOV IVAN",
      "match_type": "exact",
      "confidence": 0.95
    }
  ],
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.sanctionedPersons"
}

focus_pep field — PEP register hit:

{
  "items": [
    {
      "full_name": "IVANOV IVAN IVANOVICH",
      "category": "national_pep",
      "position": "State Duma deputy",
      "checked_at": "2026-04-24T10:15:00Z"
    }
  ],
  "source": "focus.pepSearch"
}

focus_person_bankruptcy field — individual bankruptcy:

{
  "is_bankrupt": false,
  "items": [],
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.personBankruptcy"
}

When bankruptcy is found, the item fields include case_number, arbitr_court, stage (observation / financial recovery / external administration / bankruptcy proceedings / asset liquidation), start_date, manager_full_name, etc.

focus_affiliates field — affiliated companies (where the applicant is a director / founder / beneficial owner):

{
  "items": [
    {
      "ogrn": "1027700123456",
      "inn": "7701234567",
      "company_name": "OOO Example",
      "role": "director",
      "share_percent": 50.0,
      "is_sanctioned": false,
      "is_bankrupt": false
    }
  ],
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.personAffiliates"
}

You can restrict the affiliate fields via the affiliate_fields_visibility setting in the AML step configuration — for example, hide ownership share from non-admin roles.

focus_smz_status field — self-employed (NPD) status:

{
  "status": "registered",
  "registered_at": "2023-01-15",
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.smzGetStatus"
}

status values: registered (self-employed), not_registered, unknown (could not be checked — for example, no INN or FNS refusal).

focus_fssp_summary field — Federal Bailiff Service records (sole proprietors only):

{
  "total_debt_rub": 1250000,
  "open_cases_count": 3,
  "items": [
    {
      "case_number": "12345/24/77001-IP",
      "debt_amount_rub": 500000,
      "subject": "Alimony",
      "status": "open"
    }
  ],
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.fssp"
}

focus_court_summary field — court cases (sole proprietors only):

{
  "total_cases": 5,
  "as_plaintiff": 2,
  "as_defendant": 3,
  "items": [
    {
      "case_number": "A40-12345/2024",
      "court_name": "Moscow Arbitration Court",
      "role": "defendant",
      "status": "in_progress",
      "registration_date": "2024-03-15"
    }
  ],
  "checked_at": "2026-04-24T10:15:00Z",
  "source": "focus.generalCourtCases"
}

Hard-block rules

A non-empty hard_block_reason means Focus data triggered an automatic rejection regardless of the final risk_score. Possible values:

Value	Description
passport_invalid	Focus reported the passport is invalid
bankruptcy_asset_liquidation	The applicant is at the "asset liquidation" stage of bankruptcy
focus_sanctions_hit	A match was found in Focus sanctions lists
affiliate_sanctions_hit	A company affiliated with the applicant is under sanctions
fssp_debt_exceeds_threshold	FSSP debt exceeds the configured hard_block_min_fssp_debt_rub threshold

Each rule can be disabled individually in the AML step configuration (hard_block_passport_invalid, hard_block_bankruptcy_asset_sale, hard_block_focus_sanctions_hit, hard_block_affiliate_sanctions_hit, hard_block_min_fssp_debt_rub set to 0).

Per-endpoint flags

You can toggle each Focus call individually in the AML step configuration (under Flows → AML screening step):

Flag	Focus endpoint	Description
enable_focus_enrichment	—	Global switch for the entire enrichment stage
enable_sanctioned_persons_check	sanctionedPersons	Search against Focus sanctions lists
enable_pep_search_check	pepSearch	PEP register search
enable_person_bankruptcy_check	personBankruptcy	Individual bankruptcy check
enable_passport_invalid_check	checkPassport	Passport verification with a second source
enable_person_affiliates	personAffiliates	Affiliated companies search
enable_smz_check	smzSend + smzGetStatus	Self-employed status check
enable_fssp_check	fssp	FSSP check (sole proprietors only)
enable_court_cases_check	generalCourtCases	Court cases check (sole proprietors only)

If the global enable_focus_enrichment = false, the enrichment field is absent from the payload and the decision relies on Kontur.Compliance data only.

Verification link events (link.*)

Every link event carries the full verification-link record:

{
  "type": "link.consumed",
  "data": {
    "link": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "flow_id": "550e8400-e29b-41d4-a716-446655440002",
      "external_user_id": "user_12345",
      "external_reference": "ref_abc123",
      "status": "consumed",
      "session_id": "550e8400-e29b-41d4-a716-446655440001",
      "created_at": "2026-02-11T10:00:00Z",
      "activated_at": "2026-02-11T10:05:00Z",
      "consumed_at": "2026-02-11T12:00:00Z",
      "expires_at": "2026-02-14T10:00:00Z",
      "locale": "en"
    }
  }
}

The full link field schema is in the API reference (Swagger / OpenAPI).

OCR events (verification.ocr.*)

verification.ocr.corrected — an operator edited OCR results in the admin panel:

{
  "type": "verification.ocr.corrected",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440005",
    "verification_id": "550e8400-e29b-41d4-a716-446655440099",
    "fields": {
      "first_name": "JANE",
      "last_name": "DOE",
      "date_of_birth": "1990-05-15"
    }
  }
}

Manual Review Resubmit events (verification.resubmit_*)

Events for step resubmission requests by manual review operators.

verification.resubmit_requested — a reviewer asked the applicant to resubmit a step:

{
  "type": "verification.resubmit_requested",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "flow_id": "550e8400-e29b-41d4-a716-446655440003",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440005",
    "step_id": "550e8400-e29b-41d4-a716-446655440010",
    "step_type": "document_capture",
    "reason_code": "blurry",
    "client_message": "Photo is blurry, please re-upload",
    "attempt_number": 1,
    "requested_by_id": "550e8400-e29b-41d4-a716-446655440100",
    "requested_by_name": "Reviewer Name",
    "expires_at": "2026-05-04T12:00:00Z"
  }
}

Allowed reason_code values: illegible, blurry, cropped, glare, wrong_document, expired_document, partial.

verification.resubmit_fulfilled — the applicant resubmitted the requested step:

{
  "type": "verification.resubmit_fulfilled",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440002",
    "flow_id": "550e8400-e29b-41d4-a716-446655440003",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440005",
    "step_id": "550e8400-e29b-41d4-a716-446655440010",
    "reason_code": "blurry",
    "attempt_number": 1,
    "fulfilled_at": "2026-04-27T18:30:00Z"
  }
}

Manual Review Resubmit limits: up to 3 requests per session, 7-day request TTL. If the applicant does not resubmit before the TTL expires, the request is cancelled automatically.

Frequently asked questions

Lost webhook secret

A webhook secret (with the whsec_ prefix) cannot be recovered — it is shown only once when you create the endpoint.

What to do:

1. Open the OneKYC admin panel.

2. Go to Webhooks.

3. Click "Rotate secret" next to the endpoint.

4. Copy the new secret — it is shown only once.

5. Update the secret in your application configuration.

Note: during rotation, both secrets (old and new) are valid at the same time for a 24-hour grace period. This keeps webhook delivery uninterrupted while you update credentials. The X-Onekyc-Signature header carries both v1=<old_signature> and v2=<new_signature>.

No incoming webhooks

If webhooks stop arriving, run through the following checks:

1. Endpoint status in the admin panel

• Open the Webhooks section of the admin panel.

• Check the endpoint status (active / disabled / error).

• Review the delivery log — it lists response codes and error details.

2. Server reachability

• The URL must be publicly reachable over HTTPS (HTTP is not supported).

• Make sure your firewall does not block incoming requests from OneKYC.

• Verify the SSL certificate is valid (self-signed certificates are not supported).

3. Webhook handler code

• Your endpoint must respond with HTTP 2xx (200, 201, 204) within 30 seconds.

• If processing takes longer, return 200 OK immediately and process asynchronously.

• Check your application log for signature validation errors.

4. Event types

• Confirm that the required event types are enabled in the endpoint settings.

• If you selected "All events", confirm that events are actually being generated (sessions created, verifications run, etc.).

5. Dead-letter queue

If the system cannot deliver a webhook after 5 attempts (with exponential backoff up to 24 hours), the event is moved to the dead-letter queue. Undelivered events are visible in the admin panel, where you can trigger manual redelivery.

Endpoint testing:

To validate an endpoint, click "Send test webhook" in the admin panel. In the dialog, choose an event type (for example, verification.approved) — the system sends a test payload of that type with a valid HMAC-SHA256 signature. The test event identifier carries the evt_test_ prefix.

Contacting support

If you run into trouble with webhooks, use the following channels:

1. Documentation and examples

• Re-read this section and the code examples above.

• See the API reference (Swagger / OpenAPI) for the detailed specification.

2. Technical support

• Email: [e-mail]

• Telegram: @OneKYC_Support

• Hours: Mon–Fri, 10:00–19:00 (GMT+6, Almaty)

3. Critical issues

For critical issues blocking production:

• Send a request to support with "URGENT" in the subject line.

• Include tenant_id, the endpoint URL, and sample error log entries.

• A response is provided within 2 hours during business hours.

4. Bug reports and improvement suggestions

If you find a bug in the webhook system or have suggestions:

• Open a request through the admin panel customer area.

• Or send the details to [e-mail].

---

For full details on payload format, headers, and retry policy, see the API reference (Swagger / OpenAPI).