Skip to content
API reference Get API keys

Integration · Chapter 6

Webhooks

GOXOST KYC sends a signed HTTPS request to your server the moment something happens: a result is ready, a case needs review, a certificate is issued. This chapter shows how to receive these events safely.

9 min read

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

  1. Open Webhooks in the panel and press Add endpoint.
  2. Enter the Endpoint URL, for example https://shop.uz/kyc/webhook.
  3. Choose the environment (Sandbox or Live) and Which events to send. All events is recommended: events we add later are sent too.
  4. Save. The signing secret (whsec_…) is shown only once — copy it into your server configuration.
  5. 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).
Note

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.

Important

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 whole whsec_… 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
Tip

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} or GET /applicants/{id}.
  • Compare verification_id with the applicant's last_verification_id to 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.reviewed event or a GET /verifications/{id} call.
  • Handle all final events. GREEN/RED comes in verification.completed; an ON_HOLD case is closed later by verification.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 env in the body.
  • Watch the endpoint status. Email alerts for failing endpoints are not sent yet — check status in GET /webhooks or the panel.
  • Test the whole path in sandbox: the external_id suffix chooses the mock result (…-expired, …-hold, …), and webhooks are sent exactly as in live. See Sandbox.