Create an endpoint
An endpoint is a URL on your server that accepts POST requests with a JSON body. Endpoints belong to one environment: sandbox endpoints get events made with sk_test_… keys, live endpoints get real results.
In the panel
- Open Webhooks in the panel and press Add endpoint.
- Enter the Endpoint URL, for example
https://shop.uz/kyc/webhook. - Choose the environment (Sandbox or Live) and Which events to send. All events is recommended: events we add later are sent too.
- Save. The signing secret (
whsec_…) is shown only once — copy it into your server configuration. - Press Send test event and check that your server answers with HTTP 2xx.
With the 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.
Response 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_…"
}
Use ["*"] as events to receive every event. Manage endpoints with GET /webhooks, PATCH /webhooks/{id} (for example {"is_active": false} to pause deliveries) and DELETE /webhooks/{id} — see the API reference.
URL rules:
https://only, port 443 or 8443, no user name or password in the URL.- The host must resolve to public IP addresses only. Local, private, link-local and other special ranges are rejected with
400 validation_failed(fields.url). The check is repeated before every delivery. - Redirects are not followed — point the endpoint at the final URL.
- At most 10 endpoints per environment (
422 unprocessable).
The secret cannot be shown again. To rotate it, create a new endpoint, switch your server to the new secret, then delete the old endpoint.
Events
Every event has the same envelope. By default the body has no personal data — only IDs, decisions and reason codes.
| Field | Description |
|---|---|
id |
Event ID, evt_…. The same for every retry of this event. |
type |
Event name from the table below. |
created_at |
When the event happened (ISO 8601, UTC). |
env |
sandbox or live. |
data |
Event data, depends on type. |
| Event | When | data |
|---|---|---|
applicant.created |
An applicant was created | applicant_id, external_id |
session.started |
The person gave consent and started the flow | applicant_id, external_id, session_id |
verification.submitted |
All steps were submitted; checks are running | applicant_id, external_id, session_id |
verification.completed |
Final decision: GREEN or RED |
applicant_id, external_id, verification_id, decision, decision_type, reject_labels |
verification.on_hold |
Manual review is needed (ON_HOLD) |
same as verification.completed |
verification.reviewed |
Your reviewer decided, or the review deadline passed and the system cancelled the check (REVIEW_EXPIRED) |
same as verification.completed |
verification.review_reminder |
An ON_HOLD case is still waiting: right away, 2 days and 24 hours before the deadline |
verification_id, applicant_id, review_deadline_at, hours_left |
certificate.issued |
A certificate (or a new version) was issued, about 5 minutes after the final decision | see the example below |
applicant.reverification_due |
A GREEN result expires in 30 days (stage: due_soon) or has expired (stage: expired) |
applicant_id, verification_id, valid_until, stage |
applicant.reset |
The applicant was reopened for a new attempt | applicant_id, external_id |
applicant.deleted |
The applicant's data is being erased | applicant_id, external_id (the original value) |
aml.match |
Ongoing sanctions monitoring found a match — planned, not sent yet; you can already subscribe | — |
webhook.test |
You pressed Send test event or called POST /webhooks/{id}/test |
webhook_id |
For one session the order is session.started → verification.submitted → verification.completed or verification.on_hold. An ON_HOLD case later ends with 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 is final or retry for RED and null for GREEN. Fetch the full result (checks, document data) with 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"
}
}
Download the files with your API key — see Certificates. supersedes holds the old certificate ID when a re-review replaced it.
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"
}
}
Document data in the webhook (opt-in)
If you need the extracted identity data right in the event, turn on Include document data in «Result ready» (panel → Webhooks → endpoint → Edit) or send "include_document_data": true in POST/PATCH /webhooks. Then verification.completed also carries document_data (the same shape as document.data in GET /verifications/{id}) and document_data_status: included, not_stored (data is no longer kept) or not_applicable (age-only flow). For certificate.issued the event also carries the signed certificate, pdf_base64 and certificate_status.
With this option the body contains personal data. Always verify the signature, never write the body to logs, and apply your own retention period.
Verify the signature
Every request carries the header:
KYC-Signature: t=1762682652,v1=5f1c0a…e93b
t— Unix time (seconds) when this attempt was signed.v1— hex HMAC-SHA256 of the string{t}.{raw_body}, keyed with your endpoint secret (the wholewhsec_…string).
To verify: take the raw request body exactly as received (do not parse and re-encode the JSON), compute the HMAC, compare it with v1 in constant time, and reject the request if t is more than 5 minutes away from your clock. Each retry is signed again with a fresh 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
Requests come with Content-Type: application/json and User-Agent: kyc-webhooks/1. Do not rely on the sender's IP address — the signature is the only proof that the event came from GOXOST KYC.
Retries and delivery log
A delivery succeeds when your server answers with any 2xx status within 5 seconds (connection timeout 3 seconds). Anything else — another status, a timeout, a redirect, a TLS error — is a failure, and the event is sent again after:
| Retry | 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|---|
| Delay after the previous attempt | 1 min | 5 min | 30 min | 2 h | 6 h | 24 h |
That is 7 attempts in total over about 33 hours. If all of them fail, the delivery becomes failed and the endpoint's status becomes failing; the next successful delivery clears it. After 10 failures in a row, deliveries to the endpoint pause for 10 minutes and then continue.
Delivery log. The endpoint page in the panel shows recent events with the server answer and a Retry button. Through the 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"
}
]
}
The log returns the last 100 deliveries, newest first. Delivery status is pending, delivered or failed. Finished deliveries are removed from the log after 30 days.
Manual retry. POST /webhooks/deliveries/{id}/retry sends the delivery right away (even while the endpoint is paused); if it fails, the normal schedule continues. It returns {"status": "pending"} — watch the log for the outcome.
Test event. POST /webhooks/{id}/test queues a webhook.test event and returns 202 {"delivery_id": "whd_…"}. It works even for a paused endpoint. Test and retry together are limited to 10 calls per minute per key (429 rate_limited).
Idempotency and order
Your endpoint may receive the same event more than once — for example, when your server processed it but the answer timed out. Retries also mean events can arrive out of order.
- Store the event
id(evt_…) and skip events you have already processed. The ID stays the same across retries. - Treat the webhook as a signal. Before you change anything important, read the current state with
GET /verifications/{id}orGET /applicants/{id}. - Compare
verification_idwith the applicant'slast_verification_idto ignore results of older attempts.
Best practices
- Take decisions only from the backend. The result your user sees in the browser or app is for UX only; it can be faked. Grant access only after a verified
verification.completed/verification.reviewedevent or aGET /verifications/{id}call. - Handle all final events.
GREEN/REDcomes inverification.completed; anON_HOLDcase is closed later byverification.reviewed. - Answer fast. Verify the signature, save the event, return 2xx, and do the work in a background job.
- Keep the secret on the server in an environment variable or secret store; never in a mobile app or front-end code.
- Separate environments. Use a sandbox endpoint while you develop and check
envin the body. - Watch the endpoint status. Email alerts for failing endpoints are not sent yet — check
statusinGET /webhooksor the panel. - Test the whole path in sandbox: the
external_idsuffix chooses the mock result (…-expired,…-hold, …), and webhooks are sent exactly as in live. See Sandbox.