Создайте адрес
Адрес (endpoint) — это URL на вашем сервере, который принимает POST-запросы с телом в JSON. Каждый адрес относится к одному окружению: тестовые адреса получают события, созданные ключами sk_test_…, боевые адреса — реальные результаты.
В панели
- Откройте в панели раздел Вебхуки и нажмите Добавить адрес.
- Укажите Адрес (URL), например
https://shop.uz/kyc/webhook. - Выберите окружение (Тест или Боевой) и Какие события отправлять. Рекомендуем Все события: события, которые мы добавим позже, тоже будут приходить.
- Сохраните. Секрет подписи (
whsec_…) показывается только один раз — сразу сохраните его в конфигурации сервера. - Нажмите Отправить тестовое событие и убедитесь, что сервер отвечает HTTP 2xx.
Через API
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.
Ответ 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_…"
}
Чтобы получать все события, передайте в events значение ["*"]. Управлять адресами можно через GET /webhooks, PATCH /webhooks/{id} (например, {"is_active": false} приостанавливает доставку) и DELETE /webhooks/{id} — см. справочник API.
Требования к URL:
- Только
https://, порт 443 или 8443, без имени пользователя и пароля в URL. - Хост должен разрешаться только в публичные IP-адреса. Локальные, частные, link-local и другие специальные диапазоны отклоняются с
400 validation_failed(fields.url). Проверка повторяется перед каждой доставкой. - Редиректы не выполняются — указывайте конечный URL.
- Не больше 10 адресов на окружение (
422 unprocessable).
Секрет нельзя показать повторно. Чтобы сменить его, создайте новый адрес, переключите сервер на новый секрет и удалите старый адрес.
События
У всех событий одинаковая обёртка. По умолчанию в теле нет персональных данных — только идентификаторы, решения и коды причин.
| Поле | Описание |
|---|---|
id |
Идентификатор события, evt_…. Одинаковый во всех повторах этого события. |
type |
Название события из таблицы ниже. |
created_at |
Когда произошло событие (ISO 8601, UTC). |
env |
sandbox или live. |
data |
Данные события, зависят от type. |
| Событие | Когда | data |
|---|---|---|
applicant.created |
Создан заявитель | applicant_id, external_id |
session.started |
Человек дал согласие и начал проверку | applicant_id, external_id, session_id |
verification.submitted |
Все шаги отправлены, идут проверки | applicant_id, external_id, session_id |
verification.completed |
Итоговое решение: GREEN или RED |
applicant_id, external_id, verification_id, decision, decision_type, reject_labels |
verification.on_hold |
Нужна ручная проверка (ON_HOLD) |
как у verification.completed |
verification.reviewed |
Ваш проверяющий принял решение, или срок проверки истёк и система отменила проверку (REVIEW_EXPIRED) |
как у verification.completed |
verification.review_reminder |
Кейс ON_HOLD всё ещё ждёт: сразу, за 2 дня и за 24 часа до срока |
verification_id, applicant_id, review_deadline_at, hours_left |
certificate.issued |
Выпущена справка (или её новая версия), примерно через 5 минут после итогового решения | см. пример ниже |
applicant.reverification_due |
Результат GREEN истекает через 30 дней (stage: due_soon) или уже истёк (stage: expired) |
applicant_id, verification_id, valid_until, stage |
applicant.reset |
Заявитель снова открыт для новой попытки | applicant_id, external_id |
applicant.deleted |
Данные заявителя удаляются | applicant_id, external_id (исходное значение) |
aml.match |
Постоянный мониторинг санкций нашёл совпадение — запланировано, пока не отправляется; подписаться уже можно | — |
webhook.test |
Вы нажали Отправить тестовое событие или вызвали POST /webhooks/{id}/test |
webhook_id |
В рамках одной сессии порядок такой: session.started → verification.submitted → verification.completed или verification.on_hold. Кейс ON_HOLD позже завершается событием verification.reviewed.
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 — final или retry, для GREEN — null. Полный результат (проверки, данные документа) получайте через GET /verifications/{id}.
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"
}
}
Файлы скачиваются с вашим API-ключом — см. Справки. В supersedes — идентификатор старой справки, если его заменила повторная проверка.
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"
}
}
Данные документа в вебхуке (по желанию)
Если извлечённые данные личности нужны прямо в событии, включите Добавлять данные документа в событие «Результат готов» (панель → Вебхуки → адрес → Изменить) или передайте "include_document_data": true в POST/PATCH /webhooks. Тогда verification.completed дополнительно содержит document_data (та же структура, что document.data в GET /verifications/{id}) и document_data_status: included, not_stored (данные больше не хранятся) или not_applicable (сценарий «только возраст»). Для certificate.issued событие также содержит подписанный certificate, pdf_base64 и certificate_status.
С этой опцией тело содержит персональные данные. Всегда проверяйте подпись, никогда не пишите тело в логи и применяйте собственный срок хранения.
Проверьте подпись
Каждый запрос содержит заголовок:
KYC-Signature: t=1762682652,v1=5f1c0a…e93b
t— Unix-время (в секундах), когда подписана эта попытка.v1— HMAC-SHA256 в hex от строки{t}.{raw_body}, ключ — секрет вашего адреса (вся строкаwhsec_…).
Как проверять: возьмите сырое тело запроса ровно в том виде, в каком оно пришло (не разбирайте и не кодируйте JSON заново), вычислите HMAC, сравните его с v1 за постоянное время и отклоните запрос, если t отличается от ваших часов больше чем на 5 минут. Каждый повтор подписывается заново со свежим t.
<?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
Запросы приходят с Content-Type: application/json и User-Agent: kyc-webhooks/1. Не полагайтесь на IP-адрес отправителя — только подпись доказывает, что событие пришло от GOXOST KYC.
Повторы и журнал доставки
Доставка успешна, если ваш сервер ответил любым статусом 2xx в течение 5 секунд (тайм-аут соединения — 3 секунды). Всё остальное — другой статус, тайм-аут, редирект, ошибка TLS — считается неудачей, и событие отправляется снова через:
| Повтор | 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|---|
| Пауза после предыдущей попытки | 1 мин | 5 мин | 30 мин | 2 ч | 6 ч | 24 ч |
Всего 7 попыток примерно за 33 часа. Если все они неудачны, доставка получает статус failed, а status адреса становится failing; следующая успешная доставка снимает этот статус. После 10 неудач подряд доставка на адрес приостанавливается на 10 минут, затем продолжается.
Журнал доставки. На странице адреса в панели видны последние события с ответом сервера и кнопкой Повторить. Через API:
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"
}
]
}
Журнал возвращает последние 100 доставок, новые сверху. status доставки — pending, delivered или failed. Завершённые доставки удаляются из журнала через 30 дней.
Ручной повтор. POST /webhooks/deliveries/{id}/retry сразу отправляет доставку (даже если адрес приостановлен); при неудаче продолжается обычное расписание. Ответ — {"status": "pending"}, результат смотрите в журнале.
Тестовое событие. POST /webhooks/{id}/test ставит в очередь событие webhook.test и возвращает 202 {"delivery_id": "whd_…"}. Работает и для приостановленного адреса. Тест и повтор вместе ограничены 10 вызовами в минуту на ключ (429 rate_limited).
Идемпотентность и порядок
Одно и то же событие может прийти несколько раз — например, если сервер обработал его, но ответ не успел дойти. Из-за повторов события также могут приходить не по порядку.
- Сохраняйте
idсобытия (evt_…) и пропускайте уже обработанные. Идентификатор не меняется между повторами. - Считайте вебхук сигналом. Прежде чем менять что-то важное, прочитайте текущее состояние через
GET /verifications/{id}илиGET /applicants/{id}. - Сравнивайте
verification_idсlast_verification_idзаявителя, чтобы игнорировать результаты старых попыток.
Рекомендации
- Принимайте решения только на бэкенде. Результат, который пользователь видит в браузере или приложении, нужен только для интерфейса — его можно подделать. Открывайте доступ только после проверенного события
verification.completed/verification.reviewedили вызоваGET /verifications/{id}. - Обрабатывайте все итоговые события.
GREEN/REDприходит вverification.completed; кейсON_HOLDзакрывается позже событиемverification.reviewed. - Отвечайте быстро. Проверьте подпись, сохраните событие, верните 2xx, а работу выполните в фоновой задаче.
- Храните секрет на сервере — в переменной окружения или хранилище секретов; никогда в мобильном приложении или фронтенд-коде.
- Разделяйте окружения. Во время разработки используйте тестовый адрес и проверяйте
envв теле. - Следите за статусом адреса. Письма о неработающих адресах пока не отправляются — проверяйте
statusвGET /webhooksили в панели. - Проверьте весь путь в тестовом режиме: суффикс
external_idвыбирает тестовый результат (…-expired,…-hold, …), а вебхуки отправляются так же, как в боевом режиме. См. Тестовый и боевой режимы.