Guide d'implémentation des webhooks

Enregistrez une URL HTTPS et recevez des notifications d'événements en temps réel signées HMAC lorsque des signaux smart-money se déclenchent — pas de polling. Ce guide couvre l'enregistrement, le filtrage des événements, la vérification des signatures et le comportement des nouvelles tentatives.

Aperçu

Au lieu d'interroger /v1/confirm ou le flux de signaux, enregistrez un webhook et Smart Money API enverra une requête POST avec l'événement à votre endpoint dès qu'un signal correspondant se déclenche. Chaque livraison est signée avec HMAC-SHA256 pour que vous puissiez vérifier qu'elle provient bien de nous.

Les webhooks sortants sont disponibles sur les plans Pro et Enterprise.

Enregistrer un webhook

Envoyez une requête POST à /v1/webhooks avec votre clé API dans l'en-tête X-API-Key . Le corps doit contenir quatre champs :

Champ	Type	Description
url	string	Endpoint HTTPS pour recevoir les événements (doit commencer par `https://`)
events	array	Noms des événements à recevoir, par ex. `["HIGH","MEDIUM","VETO"]` ou `["*"]`
symbols	array	Symboles à filtrer, par ex. `["BTC","ETH"]` ou `["*"]`
secret	string	Votre secret de signature — au moins 16 caractères. Stocké sous forme hachée ; conservez la valeur brute de votre côté pour vérifier les signatures.

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 enregistré. Testez avec POST /v1/webhooks/test"
}

Filtres d'événements

Les livraisons se déclenchent pour les événements dont le nom et le symbole correspondent à votre enregistrement. Les noms d'événements typiques sont les niveaux de confiance de confirmation — HIGH, MEDIUM, VETO — plus les événements génériques SIGNAL . Utilisez ["*"] pour recevoir tous les événements ou tous les symboles.

Livraison & en-têtes

Chaque livraison est une requête HTTP POST avec un corps JSON et ces en-têtes :

En-tête	Valeur
X-SmartMoney-Event	Le nom de l'événement (par ex. `HIGH`)
X-SmartMoney-Signature	Digest HMAC-SHA256 hexadécimal du corps de la requête (voir ci-dessous)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Répondez avec n'importe quel statut 2xx pour accuser réception. Un statut non-2xx (ou un timeout) déclenche une nouvelle tentative.

Vérification des signatures

La signature dans X-SmartMoney-Signature est un digest HMAC-SHA256 hexadécimal du corps de la requête. La clé HMAC est le digest SHA-256 hexadécimal du secret que vous avez enregistré (votre secret brut n'est jamais stocké que sous forme hachée de notre côté). Pour vérifier : dérivez la clé, calculez le HMAC du corps brut et comparez avec une vérification en temps constant. Rejetez toute requête qui échoue.

Python (récepteur Flask)
import hashlib, hmac
from flask import Flask, request, abort

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # la valeur que vous avez enregistrée

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # octets exacts du corps
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # clé 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()
    # ... agissez sur event["event"], event["symbol"], event["composite"] ...
    return "", 200

Node.js (récepteur Express)
import crypto from "crypto";
import express from "express";

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

// Capturez le corps brut pour que la vérification de signature utilise les octets exacts.
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());
  // ... agissez sur event ...
  res.status(200).end();
});

Vérifiez par rapport au corps brut, non analysé de la requête — une ré-sérialisation du JSON analysé peut changer l'ordre des octets ou l'espacement et faire échouer la vérification.

Nouvelles tentatives

Si votre endpoint ne renvoie pas un statut 2xx (ou dépasse le délai — le timeout de livraison est de 10s), Smart Money API effectue jusqu'à 3 nouvelles tentatives avec un backoff exponentiel (environ 1s, 4s, puis 16s). Rendez votre gestionnaire idempotent pour qu'un événement relivré puisse être traité en toute sécurité deux fois.

Webhooks entrants (TradingView)

Séparément, vous pouvez nous envoyer une alerte entrante . POST /v1/tradingview/webhook reçoit une alerte TradingView, la traite via /confirm, et renvoie la confirmation. Comme TradingView ne peut pas envoyer d'en-têtes personnalisés, il s'authentifie via un champ secret dans le corps JSON (pas X-API-Key). Envoyez secret, symbol, et direction (long/short); optionnellement timeframe, strategy, et price.

Prêt à connecter des signaux en temps réel ?

Obtenez votre clé API