Webhook Implementation Guide

Zaregistrujte HTTPS URL a přijímejte události v reálném čase podepsané HMAC, když se aktivují smart-money signály — bez dotazování. Tento průvodce pokrývá registraci, filtrování událostí, ověřování podpisů a chování při opakovaných pokusech.

Přehled

Namísto dotazování /v1/confirm nebo feedu signálů zaregistrujte webhook a Smart Money API bude POSTovat událost na váš endpoint ve chvíli, kdy se aktivuje odpovídající signál. Každé doručení je podepsáno HMAC-SHA256, takže můžete ověřit, že skutečně pochází od nás.

Odchozí webhooky jsou dostupné na Pro a Enterprise plánech.

Registrace Webhooku

POST na /v1/webhooks s vaším API klíčem v hlavičce X-API-Key Hlavička. Tělo požadavku musí obsahovat čtyři pole:

Pole	Typ	Popis
url	string	HTTPS endpoint pro příjem událostí (musí začínat `https://`)
events	array	Názvy událostí k příjmu, např. `["HIGH","MEDIUM","VETO"]` nebo `["*"]`
symbols	array	Symboly k filtrování, např. `["BTC","ETH"]` nebo `["*"]`
secret	string	Váš podpisový secret — alespoň 16 znaků. Ukládá se zahashovaný; zachovejte si původní hodnotu pro ověření podpisů.

cURL
curl -X POST https://api.smartmoneyapi.com/v1/webhooks \
  -H "X-API-Key: sm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/smartmoney",
    "events": ["HIGH", "MEDIUM"],
    "symbols": ["BTC", "ETH"],
    "secret": "a-long-random-secret-16-plus-chars"
  }'

201 Created
{
  "webhook_id": 42,
  "url": "https://yourapp.com/webhooks/smartmoney",
  "events": ["HIGH", "MEDIUM"],
  "symbols": ["BTC", "ETH"],
  "message": "Webhook registered. Test with POST /v1/webhooks/test"
}

Filtry událostí

Doručení se aktivuje pro události, jejichž název a symbol odpovídají vaší registraci. Typické názvy událostí jsou konfidenční úrovně — HIGH, MEDIUM, VETO — plus obecné SIGNAL události. Použijte ["*"] pro příjem všech událostí nebo všech symbolů.

Doručení & Hlavičky

Každé doručení je HTTP POST s JSON tělem a těmito hlavičkami:

Hlavička	Hodnota
X-SmartMoney-Event	Název události (např. `HIGH`)
X-SmartMoney-Signature	HMAC-SHA256 hex digest těla požadavku (viz níže)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

Příklad payloadu
{
  "event": "HIGH",
  "ts": "2026-07-01T18:22:05Z",
  "symbol": "BTC",
  "direction": "long",
  "confidence": "HIGH",
  "composite": 0.74,
  "webhook_id": 42
}

Odpovězte s jakýmkoli 2xx statusem k potvrzení. Non-2xx (nebo timeout) spustí opakovaný pokus.

Ověřování podpisů

Podpis v X-SmartMoney-Signature je HMAC-SHA256 hex digest těla požadavku. HMAC klíč je SHA-256 hex digest secretu, který jste zaregistrovali (váš původní secret je u nás uložen pouze zahashovaný). Pro ověření: odvoďte klíč, HMACujte původní tělo a porovnejte s časově konstantní kontrolou. Zamítněte jakýkoli požadavek, který neprojde.

Python (Flask receiver)
import hashlib, hmac
from flask import Flask, request, abort

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # hodnota, kterou jste zaregistrovali

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # přesné bajty těla
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # HMAC klíč = sha256(secret) hex
    expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # ... zpracujte event["event"], event["symbol"], event["composite"] ...
    return "", 200

Node.js (Express receiver)
import crypto from "crypto";
import express from "express";

const app = express();
const MY_SECRET = "a-long-random-secret-16-plus-chars";

// Zachyťte původní tělo, aby kontrola podpisu použila přesné bajty.
app.post("/webhooks/smartmoney", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.get("X-SmartMoney-Signature") || "";
  const key = crypto.createHash("sha256").update(MY_SECRET).digest("hex");
  const expected = crypto.createHmac("sha256", key).update(req.body).digest("hex");
  const ok = expected.length === sig.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body.toString());
  // ... zpracujte event ...
  res.status(200).end();
});

Ověřte proti původnímu, neparsovanému tělu požadavku — pře-serializace parsovaného JSONu může změnit pořadí bajtů nebo mezery a zrušit kontrolu.

Opakované pokusy

Pokud váš endpoint nevrátí 2xx (nebo dojde k timeoutu — timeout doručení je 10s), Smart Money API provede až 3 opakované pokusy s exponenciálním backoffem (přibližně 1s, 4s, pak 16s). Ujistěte se, že váš handler je idempotentní, aby bylo bezpečné zpracovat znovu doručenou událost.

Příchozí Webhooky (TradingView)

Samostatně můžete poslat příchozí alert k nám. POST /v1/tradingview/webhook přijímá TradingView alert, prožene ho přes /confirma vrátí potvrzení. Protože TradingView nemůže posílat vlastní hlavičky, autentizuje se přes secret pole v JSON těle (ne X-API-Key). Pošlete secret, symbola direction (long/short); volitelně timeframe, strategya price.

Připraveni připojit signály v reálném čase?

Získejte svůj API klíč