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
- Panelda Webhooklar boʻlimini oching va Manzil qoʻshish tugmasini bosing.
- Manzil (URL) maydoniga manzilni kiriting, masalan
https://shop.uz/kyc/webhook. - Muhitni (Sinov yoki Ishchi) va Qaysi hodisalar yuborilsin ni tanlang. Barcha hodisalar ni tavsiya qilamiz: keyin qoʻshiladigan hodisalar ham keladi.
- Saqlang. Imzo siri (
whsec_…) faqat bir marta koʻrsatiladi — uni darhol server sozlamalaringizga nusxalang. - 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).
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.
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 (butunwhsec_…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
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
idsini (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}yokiGET /applicants/{id}bilan oʻqing. - Eski urinishlar natijalarini eʼtiborsiz qoldirish uchun
verification_idni arizachininglast_verification_idsi 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.reviewedhodisasi yokiGET /verifications/{id}chaqiruvidan keyin bering. - Barcha yakuniy hodisalarni qayta ishlang.
GREEN/REDverification.completedda keladi;ON_HOLDish keyinroqverification.reviewedbilan 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
envni tekshiring. - Manzil holatini kuzating. Ishlamayotgan manzillar haqida email ogohlantirish hozircha yuborilmaydi —
GET /webhooksdagi yoki paneldagistatusni tekshiring. - Butun yoʻlni sinov rejimida sinang:
external_idqoʻshimchasi soxta natijani tanlaydi (…-expired,…-hold, …), webhooklar esa xuddi ishchi rejimdagidek yuboriladi. Sinov va ishchi rejim bobiga qarang.