HgBest

Identifies obscure global risks impacting materials or logistics routes. Provides actionable disruption predictions.

Request

{
  "material_type":    "Lithium-ion batteries",
  "region_of_origin": "Global",
  "logistics_route":  "Asia to Europe via Suez Canal"
}

Response

{
  "request_id": "risk-alert-abc-123",
  "risk_alert": {
    "risk_score_10":          7.5,
    "event_type":             "Geopolitical / Logistical Disruption",
    "anticipated_delay_days": "10-14 days",
    "summary":                "Persistent rerouting via Cape of Good Hope…",
    "immediate_recommendation": "Develop multi-modal logistics strategy."
  }
}

Synthesizes market chatter, regulatory filings, and historical correlations into a quantifiable Portfolio Impact Signal.

Request

{
  "market_focus":                 "Tech sector",
  "regulatory_filings_keywords":  ["SEC filing ABC"],
  "news_keywords":                ["AI regulation", "semiconductor shortage"]
}

Response

{
  "signal_id":           "finance-signal-def-456",
  "overall_risk_signal": "Caution - Moderate Volatility Expected",
  "impact_prediction": {
    "score_0_100":            65,
    "volatility_index_change": "+1.8%",
    "key_insight":            "Regulatory uncertainty driving market volatility."
  },
  "sector_exposure": [{
    "sector":          "Technology",
    "exposure_level":  "HIGH",
    "sentiment_delta": -0.92
  }]
}

Detects divergence between disparate data streams and asset price, signalling high-probability unexpected price movements.

Request

{
  "asset_ticker":       "BTC",
  "additional_context": "Recent SEC comments, institutional adoption rising."
}

Response

{
  "asset_ticker":             "BTC",
  "divergence_score_percent": 85,
  "directional_bias":         "Uptrend Probability",
  "top_causal_factor":        "Growing institutional capital inflows.",
  "predictive_factors": [{
    "name":        "Social Sentiment (Weighted)",
    "value":       "0.88",
    "description": "Significant positive sentiment across crypto channels."
  }],
  "advice": "Monitor for volume confirmation above $70,000."
}

Performs KYC (document extraction + face match) and AML (sanctions screening) on an ID document and selfie. Returns immediately with a request_id; final result is POSTed to your webhook_url.

Request

{
  "id_image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
  "selfie_base64":   "data:image/jpeg;base64,/9j/4BBR...",
  "webhook_url":     "https://yourserver.com/your-webhook",
  "metadata":        { "customer_id": "cus_123" }
}

Immediate Response (202 Accepted)

{
  "request_id":   "550e8400-e29b-41d4-a716-446655440000",
  "status":       "PROCESSING",
  "submitted_at": "2025-06-01T12:00:00.000Z"
}

Webhook Payload (final result)

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status":     "APPROVED",
  "reason_codes": [],
  "kyc": {
    "document_type":  "passport",
    "full_name":      "Jane Doe",
    "expiry_date":    "2030-05-14",
    "is_expired":     false,
    "doc_confidence": 0.93
  },
  "face_match": { "score": 0.91, "passed": true },
  "liveness": {
    "appears_live":        true,
    "liveness_confidence": 0.92,
    "passed":              true,
    "notes":               null
  },
  "aml": { "sanctions_checked": true, "sanctions_hit": false }
}

Verifying the Webhook is Genuine

Every webhook POST from HgBest includes two headers you must verify:

X-HgBest-Signature  — HMAC-SHA256 hex string (proof it is from us)
X-HgBest-Timestamp  — Unix milliseconds

Our public webhook secret — copy this into your server:

hgbest_whsec_122f09c08413e62e79d95ccb233502554bc07564207c14315f9eebb8b312c28c

Node.js — verify and receive webhook:

const crypto = require('crypto');

app.post('/your-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hgbest-signature'];
  const timestamp = req.headers['x-hgbest-timestamp'];
  const rawBody   = req.body.toString('utf8');

  const HGBEST_WEBHOOK_SECRET = 'hgbest_whsec_122f09c08413e62e79d95ccb233502554bc07564207c14315f9eebb8b312c28c';

  const expected = crypto
    .createHmac('sha256', HGBEST_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid webhook signature');
  }

  const result = JSON.parse(rawBody);
  console.log('Status:', result.status);
  console.log('Reason codes:', result.reason_codes);
  res.status(200).send('OK');
});

Python — verify and receive webhook:

import hmac, hashlib, json

HGBEST_WEBHOOK_SECRET = 'hgbest_whsec_122f09c08413e62e79d95ccb233502554bc07564207c14315f9eebb8b312c28c'

def verify_hgbest_webhook(raw_body: str, timestamp: str, signature: str) -> bool:
    message  = f"{timestamp}.{raw_body}".encode('utf-8')
    expected = hmac.new(
        HGBEST_WEBHOOK_SECRET.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example:
# @app.route('/your-webhook', methods=['POST'])
# def receive_webhook():
#     raw_body  = request.get_data(as_text=True)
#     timestamp = request.headers.get('X-HgBest-Timestamp')
#     signature = request.headers.get('X-HgBest-Signature')
#     if not verify_hgbest_webhook(raw_body, timestamp, signature):
#         return 'Invalid signature', 401
#     result = json.loads(raw_body)
#     print('Status:', result['status'])
#     return 'OK', 200

Reason Codes

Poll for the outcome of a previously submitted verification. Only the API key that submitted the request can retrieve it.

Response

{
  "request_id":       "550e8400-...",
  "status":           "APPROVED",
  "reason_codes":     [],
  "kyc_summary":      { "document_type": "passport", "is_expired": false },
  "face_match_score": 0.91,
  "sanctions_hit":    false,
  "liveness_passed":  true,
  "submitted_at":     "2025-06-01T12:00:00.000Z",
  "completed_at":     "2025-06-01T12:00:08.000Z"
}