Guida all'Implementazione dei Webhook

Registra un URL HTTPS e ricevi notifiche di eventi in tempo reale firmate con HMAC quando si attivano i segnali smart-money — nessun polling. Questa guida copre la registrazione, il filtraggio degli eventi, la verifica della firma e il comportamento dei tentativi.

Panoramica

Invece di effettuare polling /v1/confirm o il feed dei segnali, registra un webhook e Smart Money API invierà una richiesta POST con l'evento al tuo endpoint nel momento in cui un segnale corrispondente viene attivato. Ogni consegna è firmata con HMAC-SHA256 in modo che tu possa verificare che provenga effettivamente da noi.

I webhook in uscita sono disponibili sui piani Pro ed Enterprise.

Registra un Webhook

Invia una richiesta POST a /v1/webhooks con la tua chiave API nell'intestazione X-API-Key L'oggetto deve contenere quattro campi:

Campo	Tipo	Descrizione
url	string	Endpoint HTTPS per ricevere gli eventi (deve iniziare con `https://`)
events	array	Nomi degli eventi da ricevere, ad esempio `["HIGH","MEDIUM","VETO"]` o `["*"]`
symbols	array	Simboli da filtrare, ad esempio `["BTC","ETH"]` o `["*"]`
secret	string	Il tuo segreto per la firma — almeno 16 caratteri. Memorizzato in forma hash; conserva il valore originale sul tuo lato per verificare le firme.

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 Creato
{
  "webhook_id": 42,
  "url": "https://yourapp.com/webhooks/smartmoney",
  "events": ["HIGH", "MEDIUM"],
  "symbols": ["BTC", "ETH"],
  "message": "Webhook registrato. Test con POST /v1/webhooks/test"
}

Filtri per gli Eventi

Le consegne vengono attivate per eventi il cui nome e simbolo corrispondono alla tua registrazione. I nomi degli eventi tipici sono i livelli di confidenza di conferma — HIGH, MEDIUM, VETO — più eventi generici SIGNAL . Usa ["*"] per ricevere tutti gli eventi o tutti i simboli.

Consegna & Intestazioni

Ogni consegna è una richiesta HTTP POST con un corpo JSON e queste intestazioni:

Intestazione	Valore
X-SmartMoney-Event	Il nome dell'evento (ad esempio `HIGH`)
X-SmartMoney-Signature	Digest HMAC-SHA256 esadecimale del corpo della richiesta (vedi sotto)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Rispondi con qualsiasi 2xx stato per confermare la ricezione. Un codice non 2xx (o un timeout) attiva un tentativo di ripetizione.

Verifica delle Firma

La firma in X-SmartMoney-Signature è un digest HMAC-SHA256 esadecimale del corpo della richiesta. La chiave HMAC è il digest SHA-256 esadecimale del segreto che hai registrato (il tuo segreto originale è memorizzato solo in forma hash sul nostro lato). Per verificare: deriva la chiave, calcola l'HMAC del corpo originale e confronta con un controllo a tempo costante. Rifiuta qualsiasi richiesta che non superi il controllo.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # il valore che hai registrato

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # byte esatti del corpo
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # chiave HMAC = 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()
    # ... agisci su event["event"], event["symbol"], event["composite"] ...
    return "", 200

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

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

// Cattura il corpo originale in modo che il controllo della firma utilizzi i byte esatti.
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());
  // ... agisci su event ...
  res.status(200).end();
});

Verifica rispetto al corpo originale, non analizzato della richiesta — ri-serializzare un JSON analizzato può cambiare l'ordine dei byte o gli spazi e invalidare il controllo.

Riprovare

Se il tuo endpoint non restituisce un codice 2xx (o va in timeout — il timeout di consegna è di 10s), Smart Money API riprova fino a 3 volte con backoff esponenziale (circa 1s, 4s, poi 16s). Rendi il tuo gestore idempotente in modo che un evento ri-consegnato possa essere elaborato due volte in sicurezza.

Webhook in Entrata (TradingView)

In alternativa, puoi inviare un in entrata alert a noi. POST /v1/tradingview/webhook riceve un alert da TradingView, lo elabora attraverso /confirme restituisce la conferma. Poiché TradingView non può inviare intestazioni personalizzate, l'autenticazione avviene tramite un secret campo nel corpo JSON (non X-API-Key). Invia secret, symbole direction (long/short); opzionalmente timeframe, strategye price.

Pronto a collegare i segnali in tempo reale?

Ottieni la tua chiave API