Οδηγός Υλοποίησης Webhook

Καταχωρίστε μια διεύθυνση URL HTTPS και λάβετε ειδοποιήσεις συμβάντων σε πραγματικό χρόνο, υπογεγραμμένες με HMAC, όταν ενεργοποιούνται σήματα smart-money — χωρίς δημοσκόπηση. Αυτός ο οδηγός καλύπτει την εγγραφή, το φιλτράρισμα συμβάντων, την επαλήθευση υπογραφών και τη συμπεριφορά επανάληψης.

Επισκόπηση

Αντί για δημοσκόπηση /v1/confirm ή τη ροή σημάτων, καταχωρίστε ένα webhook και το Smart Money API θα στείλει ένα συμβάν στο endpoint σας τη στιγμή που ενεργοποιείται ένα αντίστοιχο σήμα. Κάθε παράδοση υπογράφεται με HMAC-SHA256, ώστε να μπορείτε να επαληθεύσετε ότι προέρχεται πράγματι από εμάς.

Τα εξερχόμενα webhooks είναι διαθέσιμα στα πλάνα Pro και Enterprise.

Εγγραφή Webhook

POST στο /v1/webhooks με το κλειδί API στο X-API-Key κεφαλίδα. Το σώμα χρειάζεται τέσσερα πεδία:

Πεδίο	Τύπος	Περιγραφή
url	string	Endpoint HTTPS για λήψη συμβάντων (πρέπει να ξεκινά με `https://`)
events	array	Ονόματα συμβάντων που θα λάβετε, π.χ. `["HIGH","MEDIUM","VETO"]` ή `["*"]`
symbols	array	Σύμβολα για φιλτράρισμα, π.χ. `["BTC","ETH"]` ή `["*"]`
secret	string	Το μυστικό σας για υπογραφή — τουλάχιστον 16 χαρακτήρες. Αποθηκεύεται κρυπτογραφημένο· διατηρήστε την ακατέργαστη τιμή στην πλευρά σας για επαλήθευση υπογραφών.

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"
}

Φίλτρα Συμβάντων

Οι παραδόσεις ενεργοποιούνται για συμβάντα των οποίων το όνομα και το σύμβολο ταιριάζουν με την εγγραφή σας. Τυπικά ονόματα συμβάντων είναι οι κάδοι εμπιστοσύνης επιβεβαίωσης — HIGH, MEDIUM, VETO — συν γενικά SIGNAL συμβάντα. Χρησιμοποιήστε ["*"] για λήψη όλων των συμβάντων ή όλων των συμβόλων.

Παράδοση & Κεφαλίδες

Κάθε παράδοση είναι ένα HTTP POST με ένα σώμα JSON και αυτές τις κεφαλίδες:

Κεφαλίδα	Τιμή
X-SmartMoney-Event	Το όνομα του συμβάντος (π.χ. `HIGH`)
X-SmartMoney-Signature	HMAC-SHA256 hex digest του σώματος του αιτήματος (δείτε παρακάτω)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

Παράδειγμα payload
{
  "event": "HIGH",
  "ts": "2026-07-01T18:22:05Z",
  "symbol": "BTC",
  "direction": "long",
  "confidence": "HIGH",
  "composite": 0.74,
  "webhook_id": 42
}

Απαντήστε με οποιαδήποτε 2xx κατάσταση για επιβεβαίωση. Μη-2xx (ή timeout) ενεργοποιεί επανάληψη.

Επαλήθευση Υπογραφών

Η υπογραφή στο X-SmartMoney-Signature είναι ένα HMAC-SHA256 hex digest του σώματος του αιτήματος. Το κλειδί HMAC είναι το SHA-256 hex digest του μυστικού που καταχωρίσατε (το ακατέργαστο μυστικό σας αποθηκεύεται μόνο κρυπτογραφημένο στην πλευρά μας). Για επαλήθευση: εξάγετε το κλειδί, υπογράψτε με HMAC το ακατέργαστο σώμα και συγκρίνετε με μια σταθερή-χρονικά έλεγχο. Απορρίψτε οποιοδήποτε αίτημα που αποτυγχάνει.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # the value you registered

@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();
});

Επαληθεύστε έναντι του ακατέργαστου, μη αναλυμένου σώματος αιτήματος — η επανα-σειριοποίηση αναλυμένου JSON μπορεί να αλλάξει τη σειρά των bytes ή τα κενά και να χαλάσει τον έλεγχο.

Επανάληψη

Εάν το endpoint σας δεν επιστρέφει ένα 2xx (ή υπερβαίνει το χρονικό όριο — το όριο παράδοσης είναι 10 δευτερόλεπτα), το Smart Money API επαναλαμβάνει έως και 3 φορές με εκθετική αναμονή (περίπου 1s, 4s, μετά 16s). Κάντε τον χειριστή σας idempotent ώστε μια επανα-παραδομένη ειδοποίηση να είναι ασφαλής για επεξεργασία δύο φορές.

Εισερχόμενα Webhooks (TradingView)

Ξεχωριστά, μπορείτε να στείλετε μια εισερχόμενη ειδοποίηση σε εμάς. POST /v1/tradingview/webhook λαμβάνει μια ειδοποίηση TradingView, την εκτελεί μέσω /confirm, και επιστρέφει την επιβεβαίωση. Επειδή το TradingView δεν μπορεί να στείλει προσαρμοσμένες κεφαλίδες, πιστοποιείται μέσω ενός secret πεδίου στο σώμα JSON (όχι X-API-Key). Στείλτε secret, symbol, και direction (long/short); προαιρετικά timeframe, strategy, και price.

Έτοιμοι να συνδέσετε σήματα σε πραγματικό χρόνο;

Αποκτήστε το κλειδί API σας