Ghid de implementare Webhook

Înregistrează un URL HTTPS și primește notificări de evenimente în timp real, semnate HMAC, când se declanșează semnalele smart-money — fără polling. Acest ghid acoperă înregistrarea, filtrarea evenimentelor, verificarea semnăturilor și comportamentul de reîncercare.

Prezentare generală

În loc de polling /v1/confirm sau feed-ul de semnale, înregistrează un webhook și Smart Money API va POSTA un eveniment către endpoint-ul tău în momentul în care se declanșează un semnal corespunzător. Fiecare livrare este semnată cu HMAC-SHA256, astfel încât să poți verifica că a venit cu adevărat de la noi.

Webhook-uri de ieșire sunt disponibile pe planurile Pro și Enterprise.

Înregistrează un Webhook

POST către /v1/webhooks cu cheia ta API în antetul X-API-Key header. Corpul necesită patru câmpuri:

Câmp	Tip	Descriere
url	string	Endpoint HTTPS pentru a primi evenimente (trebuie să înceapă cu `https://`)
events	array	Numele evenimentelor de primit, de ex. `["HIGH","MEDIUM","VETO"]` sau `["*"]`
symbols	array	Simboluri de filtrat, de ex. `["BTC","ETH"]` sau `["*"]`
secret	string	Secretul tău de semnare — cel puțin 16 caractere. Stocat hash-uit; păstrează valoarea brută pe partea ta pentru a verifica semnăturile.

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 înregistrat. Testează cu POST /v1/webhooks/test"
}

Filtre de evenimente

Livrările se declanșează pentru evenimente al căror nume și simbol se potrivesc cu înregistrarea ta. Numele tipice de evenimente sunt gălețile de încredere de confirmare — HIGH, MEDIUM, VETO — plus evenimente generice SIGNAL events. Folosește ["*"] pentru a primi toate evenimentele sau toate simbolurile.

Livrare & Antete

Fiecare livrare este un HTTP POST cu un corp JSON și aceste antete:

Antet	Valoare
X-SmartMoney-Event	Numele evenimentului (de ex. `HIGH`)
X-SmartMoney-Signature	Digest HMAC-SHA256 hex al corpului cererii (vezi mai jos)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

Exemplu de payload
{
  "event": "HIGH",
  "ts": "2026-07-01T18:22:05Z",
  "symbol": "BTC",
  "direction": "long",
  "confidence": "HIGH",
  "composite": 0.74,
  "webhook_id": 42
}

Răspunde cu orice 2xx status pentru a confirma. Non-2xx (sau un timeout) declanșează o reîncercare.

Verificarea semnăturilor

Semnătura din X-SmartMoney-Signature este un digest HMAC-SHA256 hex al corpului cererii. Cheia HMAC este digestul SHA-256 hex al secretului pe care l-ai înregistrat (secretul tău brut este stocat doar hash-uit pe partea noastră). Pentru a verifica: derivă cheia, HMAC corpul brut și compară cu o verificare constantă în timp. Respinge orice cerere care eșuează.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # valoarea pe care ai înregistrat-o

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # exact bytes of the body
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # HMAC key = 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()
    # ... act on 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";

// Capture the raw body so the signature check uses the exact bytes.
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());
  // ... act on event ...
  res.status(200).end();
});

Verifică împotriva corpului brut, neparsat al cererii — re-serializarea JSON-ului parsat poate schimba ordinea sau spațierea byte-urilor și poate strica verificarea.

Reîncercări

Dacă endpoint-ul tău nu returnează un 2xx (sau depășește timpul — timeout-ul de livrare este de 10s), Smart Money API reîncearcă de până la 3 ori cu backoff exponențial (aproximativ 1s, 4s, apoi 16s). Fă handler-ul tău idempotent, astfel încât un eveniment relivrat să fie sigur de procesat de două ori.

Webhook-uri de intrare (TradingView)

Separately, you can send an inbound alert to us. POST /v1/tradingview/webhook receives a TradingView alert, runs it through /confirm, and returns the confirmation. Because TradingView cannot send custom headers, it authenticates via a secret field in the JSON body (not X-API-Key). Send secret, symbol, and direction (long/short); optionally timeframe, strategy, and price.

Ready to wire up real-time signals?

Get your API key