Перейти к содержимому
Справочник API Получить API-ключи

Интеграция · Глава 6

Вебхуки

GOXOST KYC отправляет подписанный HTTPS-запрос на ваш сервер в момент события: готов результат, нужна ручная проверка, выпущена справка. В этой главе — как безопасно принимать такие события.

9 мин чтения

Создайте адрес

Адрес (endpoint) — это URL на вашем сервере, который принимает POST-запросы с телом в JSON. Каждый адрес относится к одному окружению: тестовые адреса получают события, созданные ключами sk_test_…, боевые адреса — реальные результаты.

В панели

  1. Откройте в панели раздел Вебхуки и нажмите Добавить адрес.
  2. Укажите Адрес (URL), например https://shop.uz/kyc/webhook.
  3. Выберите окружение (Тест или Боевой) и Какие события отправлять. Рекомендуем Все события: события, которые мы добавим позже, тоже будут приходить.
  4. Сохраните. Секрет подписи (whsec_…) показывается только один раз — сразу сохраните его в конфигурации сервера.
  5. Нажмите Отправить тестовое событие и убедитесь, что сервер отвечает 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, …), а вебхуки отправляются так же, как в боевом режиме. См. Тестовый и боевой режимы.