Asosiy qismga oʻtish
API hujjati API kalitini olish

Integratsiya · 6-bob

Webhooklar

Biror narsa yuz berishi bilan GOXOST KYC serveringizga imzolangan HTTPS soʻrov yuboradi: natija tayyor boʻldi, ish koʻrib chiqishni kutyapti, dalolatnoma berildi. Bu bobda bu hodisalarni xavfsiz qabul qilishni koʻrsatamiz.

9 daqiqa oʻqish

Manzil yaratish

Manzil (endpoint) — serveringizdagi URL. U JSON tanali POST soʻrovlarni qabul qiladi. Har bir manzil bitta muhitga tegishli: sinov manzillari sk_test_… kalitlar bilan yaratilgan hodisalarni oladi, ishchi manzillar esa haqiqiy natijalarni.

Panelda

  1. Panelda Webhooklar boʻlimini oching va Manzil qoʻshish tugmasini bosing.
  2. Manzil (URL) maydoniga manzilni kiriting, masalan https://shop.uz/kyc/webhook.
  3. Muhitni (Sinov yoki Ishchi) va Qaysi hodisalar yuborilsin ni tanlang. Barcha hodisalar ni tavsiya qilamiz: keyin qoʻshiladigan hodisalar ham keladi.
  4. Saqlang. Imzo siri (whsec_…) faqat bir marta koʻrsatiladi — uni darhol server sozlamalaringizga nusxalang.
  5. Sinov hodisasini yuborish ni bosing va serveringiz HTTP 2xx bilan javob berishini tekshiring.

API orqali

curl https://kyc.goxost.net/api/v1/webhooks \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.uz/kyc/webhook",
    "events": ["verification.completed", "verification.on_hold", "verification.reviewed"]
  }'
$response = (new GuzzleHttp\Client())->post('https://kyc.goxost.net/api/v1/webhooks', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
    'json' => [
        'url' => 'https://shop.uz/kyc/webhook',
        'events' => ['verification.completed', 'verification.on_hold', 'verification.reviewed'],
    ],
]);
$endpoint = json_decode((string) $response->getBody(), true);
// Store $endpoint['secret'] (whsec_…) now — it is returned only once.
const res = await fetch('https://kyc.goxost.net/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KYC_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://shop.uz/kyc/webhook',
    events: ['verification.completed', 'verification.on_hold', 'verification.reviewed'],
  }),
});
const endpoint = await res.json();
// Store endpoint.secret (whsec_…) now — it is returned only once.
import os, requests

res = requests.post(
    "https://kyc.goxost.net/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
    json={
        "url": "https://shop.uz/kyc/webhook",
        "events": ["verification.completed", "verification.on_hold", "verification.reviewed"],
    },
)
endpoint = res.json()
# Store endpoint["secret"] (whsec_…) now — it is returned only once.

Javob 201:

{
  "id": "whk_01m6yz3q8c5x2n7d4t9v1k0hwe",
  "url": "https://shop.uz/kyc/webhook",
  "events": ["verification.completed", "verification.on_hold", "verification.reviewed"],
  "include_document_data": false,
  "is_active": true,
  "status": "ok",
  "created_at": "2026-11-09T10:00:00Z",
  "secret": "whsec_…"
}

Barcha hodisalarni olish uchun events ga ["*"] yuboring. Manzillarni GET /webhooks, PATCH /webhooks/{id} (masalan, yuborishni toʻxtatish uchun {"is_active": false}) va DELETE /webhooks/{id} bilan boshqaring — API maʼlumotnomasiga qarang.

URL qoidalari:

  • Faqat https://, port 443 yoki 8443, URL ichida foydalanuvchi nomi va parol boʻlmaydi.
  • Host faqat ommaviy IP manzillarga yoʻnalishi kerak. Lokal, xususiy, link-local va boshqa maxsus diapazonlar 400 validation_failed (fields.url) bilan rad etiladi. Bu tekshiruv har bir yuborishdan oldin takrorlanadi.
  • Yoʻnaltirishlarga (redirect) ergashilmaydi — manzilni yakuniy URL ga qarating.
  • Har bir muhitda koʻpi bilan 10 ta manzil (422 unprocessable).
Eslatma

Sirni qayta koʻrsatib boʻlmaydi. Uni almashtirish uchun yangi manzil yarating, serveringizni yangi sirga oʻtkazing, keyin eski manzilni oʻchiring.

Hodisalar

Har bir hodisa bir xil qobiqqa ega. Standart holatda tanada shaxsiy maʼlumot yoʻq — faqat ID lar, qarorlar va sabab kodlari.

Maydon Tavsif
id Hodisa ID si, evt_…. Shu hodisaning har bir qayta yuborilishida bir xil.
type Hodisa nomi, quyidagi jadvaldan.
created_at Hodisa qachon yuz bergani (ISO 8601, UTC).
env sandbox yoki live.
data Hodisa maʼlumoti, type ga bogʻliq.
Hodisa Qachon data
applicant.created Arizachi yaratildi applicant_id, external_id
session.started Odam rozilik berdi va jarayonni boshladi applicant_id, external_id, session_id
verification.submitted Barcha qadamlar topshirildi, tekshiruvlar ketyapti applicant_id, external_id, session_id
verification.completed Yakuniy qaror: GREEN yoki RED applicant_id, external_id, verification_id, decision, decision_type, reject_labels
verification.on_hold Qoʻlda koʻrib chiqish kerak (ON_HOLD) verification.completed bilan bir xil
verification.reviewed Sizning xodimingiz qaror qildi yoki koʻrib chiqish muddati oʻtib, tizim tekshiruvni bekor qildi (REVIEW_EXPIRED) verification.completed bilan bir xil
verification.review_reminder ON_HOLD ish hali kutyapti: darhol, muddatdan 2 kun va 24 soat oldin verification_id, applicant_id, review_deadline_at, hours_left
certificate.issued Dalolatnoma (yoki uning yangi versiyasi) berildi, yakuniy qarordan taxminan 5 daqiqa keyin quyidagi namunaga qarang
applicant.reverification_due GREEN natija muddati 30 kundan keyin tugaydi (stage: due_soon) yoki tugadi (stage: expired) applicant_id, verification_id, valid_until, stage
applicant.reset Arizachi yangi urinish uchun qayta ochildi applicant_id, external_id
applicant.deleted Arizachi maʼlumotlari oʻchirilyapti applicant_id, external_id (asl qiymat)
aml.match Doimiy sanksiya monitoringi moslik topdi — rejalashtirilgan, hozircha yuborilmaydi; obuna boʻlib qoʻyish mumkin —
webhook.test Siz Sinov hodisasini yuborish ni bosdingiz yoki POST /webhooks/{id}/test ni chaqirdingiz webhook_id

Bitta sessiyada tartib shunday: session.started → verification.submitted → verification.completed yoki verification.on_hold. ON_HOLD ish keyinroq verification.reviewed bilan yakunlanadi.

verification.completed

{
  "id": "evt_01m6z0b7r4k9q2w5e8t1y3u6ia",
  "type": "verification.completed",
  "created_at": "2026-11-09T10:04:12Z",
  "env": "live",
  "data": {
    "applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
    "external_id": "user-8812",
    "verification_id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
    "decision": "RED",
    "decision_type": "retry",
    "reject_labels": ["DOC_EXPIRED"]
  }
}

decision_type — RED uchun final yoki retry, GREEN uchun null. Toʻliq natijani (tekshiruvlar, hujjat maʼlumoti) GET /verifications/{id} bilan oling.

certificate.issued

{
  "id": "evt_01m6z0f2h8n3c6v9b1m4x7z0qa",
  "type": "certificate.issued",
  "created_at": "2026-11-09T10:09:30Z",
  "env": "live",
  "data": {
    "certificate_id": "crt_01m6yyj5eaqdmyg2ty0mheaj3h",
    "version": 1,
    "verification_id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
    "applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
    "external_id": "user-8812",
    "decision": "GREEN",
    "issued_at": "2026-11-09T10:09:30Z",
    "valid_until": "2028-11-09T10:04:12Z",
    "supersedes": null,
    "verify_url": "https://kyc.goxost.net/verify/crt_01m6yyj5eaqdmyg2ty0mheaj3h",
    "certificate_url": "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate",
    "pdf_url": "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate?format=pdf"
  }
}

Fayllarni API kalitingiz bilan yuklab oling — Dalolatnomalar bobiga qarang. Qayta koʻrib chiqish eski dalolatnomani almashtirgan boʻlsa, supersedes da eski dalolatnoma ID si turadi.

applicant.reverification_due

{
  "id": "evt_01m6z1a9d3f6g2h5j8k1l4z7xb",
  "type": "applicant.reverification_due",
  "created_at": "2028-10-10T06:00:04Z",
  "env": "live",
  "data": {
    "applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
    "verification_id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
    "valid_until": "2028-11-09T10:04:12Z",
    "stage": "due_soon"
  }
}

Webhookdagi hujjat maʼlumoti (ixtiyoriy)

Hujjatdan oʻqilgan maʼlumot toʻgʻridan-toʻgʻri hodisada kerak boʻlsa, «Natija tayyor» hodisasiga hujjat maʼlumotini qoʻshish ni yoqing (panel → Webhooklar → manzil → Tahrirlash) yoki POST/PATCH /webhooks da "include_document_data": true yuboring. Shunda verification.completed da document_data (GET /verifications/{id} dagi document.data bilan bir xil shaklda) va document_data_status ham keladi: included, not_stored (maʼlumot endi saqlanmaydi) yoki not_applicable («faqat yosh» senariysi). certificate.issued da esa imzolangan certificate, pdf_base64 va certificate_status ham keladi.

Muhim

Bu sozlama yoqilganda tanada shaxsiy maʼlumot boʻladi. Imzoni doim tekshiring, tanani hech qachon logga yozmang va oʻz saqlash muddatingizni qoʻllang.

Imzoni tekshirish

Har bir soʻrovda shu sarlavha boʻladi:

KYC-Signature: t=1762682652,v1=5f1c0a…e93b
  • t — shu urinish imzolangan Unix vaqti (soniyalarda).
  • v1 — {t}.{raw_body} satrining HMAC-SHA256 qiymati (hex), kaliti — manzilingiz siri (butun whsec_… satri).

Tekshirish tartibi: soʻrov tanasini kelgan holicha, xom koʻrinishda oling (JSON ni parse qilib, qayta kodlamang), HMAC ni hisoblang, uni v1 bilan doimiy vaqtda solishtiring va t soatingizdan 5 daqiqadan koʻproq farq qilsa, soʻrovni rad eting. Har bir qayta yuborish yangi t bilan qaytadan imzolanadi.

<?php
// Plain PHP. In Laravel use $request->getContent() for the raw body.

function kyc_verify_signature(string $payload, string $header, string $secret, int $tolerance = 300): bool
{
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$key, $value] = array_pad(explode('=', trim($pair), 2), 2, '');
        $parts[$key] = $value;
    }
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!ctype_digit($t) || !preg_match('/^[0-9a-f]{64}$/', $v1)) {
        return false;
    }
    if (abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $payload, $secret);

    return hash_equals($expected, $v1);
}

$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_KYC_SIGNATURE'] ?? '';

if (!kyc_verify_signature($payload, $header, getenv('KYC_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
http_response_code(200);
// Hand $event to a queue and return quickly.
// Node.js 18+ with Express. The raw body is required — do not use express.json() on this route.
import crypto from 'node:crypto';
import express from 'express';

function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = {};
  for (const pair of String(header || '').split(',')) {
    const i = pair.indexOf('=');
    if (i > 0) parts[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
  }
  const { t = '', v1 = '' } = parts;
  if (!/^\d+$/.test(t) || !/^[0-9a-f]{64}$/.test(v1)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(v1, 'hex'));
}

const app = express();

app.post('/kyc/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.get('KYC-Signature'), process.env.KYC_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200);
  // Hand the event to a queue: handleEvent(event)
});

app.listen(3000);
# Python 3.9+ with Flask.
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["KYC_WEBHOOK_SECRET"].encode()


def verify_signature(raw_body: bytes, header: str, secret: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not (t.isascii() and t.isdigit()) or len(v1) != 64:
        return False
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret, t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


@app.post("/kyc/webhook")
def kyc_webhook():
    raw = request.get_data()
    if not verify_signature(raw, request.headers.get("KYC-Signature", ""), SECRET):
        abort(400)
    event = json.loads(raw)
    # Hand the event to a queue: handle_event(event)
    return "", 200
Maslahat

Soʻrovlar Content-Type: application/json va User-Agent: kyc-webhooks/1 bilan keladi. Yuboruvchining IP manziliga tayanmang — hodisa GOXOST KYC dan kelganini faqat imzo isbotlaydi.

Qayta yuborish va jurnal

Serveringiz 5 soniya ichida (ulanish uchun 3 soniya) istalgan 2xx status bilan javob bersa, yuborish muvaffaqiyatli hisoblanadi. Boshqa har qanday holat — boshqa status, vaqt tugashi, yoʻnaltirish, TLS xatosi — muvaffaqiyatsizlik. Bunda hodisa quyidagi vaqtdan keyin qayta yuboriladi:

Qayta yuborish 1 2 3 4 5 6
Oldingi urinishdan keyin 1 daq 5 daq 30 daq 2 soat 6 soat 24 soat

Jami taxminan 33 soat ichida 7 ta urinish. Hammasi muvaffaqiyatsiz boʻlsa, yuborish failed boʻladi, manzilning status i esa failing ga oʻtadi; keyingi muvaffaqiyatli yuborish uni tozalaydi. Ketma-ket 10 ta muvaffaqiyatsizlikdan keyin shu manzilga yuborish 10 daqiqaga toʻxtaydi, soʻng davom etadi.

Yuborish jurnali. Paneldagi manzil sahifasida soʻnggi hodisalar server javobi va Qayta yuborish tugmasi bilan koʻrinadi. API orqali:

curl https://kyc.goxost.net/api/v1/webhooks/whk_01m6yz3q8c5x2n7d4t9v1k0hwe/deliveries \
  -H "Authorization: Bearer sk_test_…"
{
  "data": [
    {
      "id": "whd_01m6z0b7s1m4p7r0t3w6y9b2nc",
      "event_id": "evt_01m6z0b7r4k9q2w5e8t1y3u6ia",
      "event": "verification.completed",
      "status": "delivered",
      "attempt": 1,
      "status_code": 200,
      "next_retry_at": null,
      "delivered_at": "2026-11-09T10:04:13Z",
      "created_at": "2026-11-09T10:04:12Z"
    }
  ]
}

Jurnal soʻnggi 100 ta yuborishni qaytaradi, eng yangisi birinchi. Yuborish status i — pending, delivered yoki failed. Tugagan yuborishlar 30 kundan keyin jurnaldan oʻchiriladi.

Qoʻlda qayta yuborish. POST /webhooks/deliveries/{id}/retry yuborishni darhol joʻnatadi (manzil toʻxtatilgan boʻlsa ham); muvaffaqiyatsiz boʻlsa, odatdagi jadval davom etadi. U {"status": "pending"} qaytaradi — natijani jurnaldan kuzating.

Sinov hodisasi. POST /webhooks/{id}/test webhook.test hodisasini navbatga qoʻyadi va 202 {"delivery_id": "whd_…"} qaytaradi. Toʻxtatilgan manzil uchun ham ishlaydi. Sinov va qayta yuborish birgalikda bitta kalit uchun daqiqasiga 10 ta chaqiruv bilan cheklangan (429 rate_limited).

Idempotentlik va tartib

Manzilingiz bir hodisani bir necha marta olishi mumkin — masalan, serveringiz uni qayta ishladi, lekin javob vaqtida yetib bormadi. Qayta yuborishlar sababli hodisalar tartibsiz kelishi ham mumkin.

  • Hodisa id sini (evt_…) saqlang va avval qayta ishlangan hodisalarni oʻtkazib yuboring. ID qayta yuborishlarda oʻzgarmaydi.
  • Webhookni signal deb biling. Muhim narsani oʻzgartirishdan oldin joriy holatni GET /verifications/{id} yoki GET /applicants/{id} bilan oʻqing.
  • Eski urinishlar natijalarini eʼtiborsiz qoldirish uchun verification_id ni arizachining last_verification_id si bilan solishtiring.

Tavsiyalar

  • Qarorni faqat backenddan oling. Foydalanuvchi brauzerda yoki ilovada koʻradigan natija faqat interfeys uchun; uni soxtalashtirish mumkin. Kirishni faqat imzosi tekshirilgan verification.completed / verification.reviewed hodisasi yoki GET /verifications/{id} chaqiruvidan keyin bering.
  • Barcha yakuniy hodisalarni qayta ishlang. GREEN/RED verification.completed da keladi; ON_HOLD ish keyinroq verification.reviewed bilan yopiladi.
  • Tez javob bering. Imzoni tekshiring, hodisani saqlang, 2xx qaytaring, ishni esa fon vazifasida bajaring.
  • Sirni serverda saqlang — muhit oʻzgaruvchisida yoki sirlar omborida; hech qachon mobil ilovada yoki front-end kodida emas.
  • Muhitlarni ajrating. Ishlab chiqish paytida sinov manzilidan foydalaning va tanadagi env ni tekshiring.
  • Manzil holatini kuzating. Ishlamayotgan manzillar haqida email ogohlantirish hozircha yuborilmaydi — GET /webhooks dagi yoki paneldagi status ni tekshiring.
  • Butun yoʻlni sinov rejimida sinang: external_id qoʻshimchasi soxta natijani tanlaydi (…-expired, …-hold, …), webhooklar esa xuddi ishchi rejimdagidek yuboriladi. Sinov va ishchi rejim bobiga qarang.