Przewodnik implementacji Webhooka

Zarejestruj adres URL HTTPS i odbieraj powiadomienia o zdarzeniach w czasie rzeczywistym, podpisane HMAC, gdy zostaną wyzwolone sygnały smart-money — bez potrzeby odpytywania. Ten przewodnik obejmuje rejestrację, filtrowanie zdarzeń, weryfikację podpisów i zachowanie przy ponownych próbach.

Przegląd

Zamiast odpytywania /v1/confirm lub kanału sygnałów, zarejestruj webhook, a Smart Money API wyśle żądanie POST z zdarzeniem do Twojego punktu końcowego w momencie wyzwolenia pasującego sygnału. Każda dostawa jest podpisana za pomocą HMAC-SHA256, abyś mógł zweryfikować, że faktycznie pochodzi od nas.

Webhooki wychodzące są dostępne w planach Pro i Enterprise.

Zarejestruj Webhook

Wyślij żądanie POST do /v1/webhooks z kluczem API w nagłówku X-API-Key . Ciało żądania musi zawierać cztery pola:

Pole	Typ	Opis
url	string	Punkt końcowy HTTPS do odbierania zdarzeń (musi zaczynać się od `https://`)
events	array	Nazwy zdarzeń do odbioru, np. `["HIGH","MEDIUM","VETO"]` lub `["*"]`
symbols	array	Symbole do filtrowania, np. `["BTC","ETH"]` lub `["*"]`
secret	string	Twój sekretny klucz podpisu — co najmniej 16 znaków. Przechowywany w postaci zahashowanej; zachowaj surową wartość po swojej stronie do weryfikacji podpisów.

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 zdarzeń

Dostawy są wyzwalane dla zdarzeń, których nazwa i symbol pasują do Twojej rejestracji. Typowe nazwy zdarzeń to przedziały pewności potwierdzenia — HIGH, MEDIUM, VETO — oraz ogólne zdarzenia SIGNAL . Użyj ["*"] , aby otrzymywać wszystkie zdarzenia lub wszystkie symbole.

Dostawa i nagłówki

Każda dostawa to żądanie HTTP POST z ciałem JSON i tymi nagłówkami:

Nagłówek	Wartość
X-SmartMoney-Event	Nazwa zdarzenia (np. `HIGH`)
X-SmartMoney-Signature	Skrót HMAC-SHA256 ciała żądania (patrz poniżej)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

Przykładowy ładunek
{
  "event": "HIGH",
  "ts": "2026-07-01T18:22:05Z",
  "symbol": "BTC",
  "direction": "long",
  "confidence": "HIGH",
  "composite": 0.74,
  "webhook_id": 42
}

Odpowiedz z dowolnym kodem statusu 2xx , aby potwierdzić. Kod inny niż 2xx (lub przekroczenie czasu) wyzwala ponowną próbę.

Weryfikacja podpisów

Podpis w X-SmartMoney-Signature to skrót HMAC-SHA256 ciała żądania. Klucz HMAC to skrót SHA-256 w postaci hex sekretu, który zarejestrowałeś (Twój surowy sekret jest przechowywany tylko w postaci zahashowanej po naszej stronie). Aby zweryfikować: wyprowadź klucz, oblicz HMAC dla surowego ciała i porównaj z stałoczasowym sprawdzeniem. Odrzuć każde żądanie, które nie przejdzie weryfikacji.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # wartość, którą zarejestrowałeś

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # dokładne bajty ciała
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # klucz 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()
    # ... działaj na podstawie event["event"], event["symbol"], event["composite"] ...
    return "", 200

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

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

// Przechwyć surowe ciało, aby sprawdzenie podpisu używało dokładnych bajtów.
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());
  // ... działaj na podstawie event ...
  res.status(200).end();
});

Weryfikuj względem surowego, nieprzetworzonego ciała żądania — ponowne serializowanie przetworzonego JSON może zmienić kolejność bajtów lub odstępy i zepsuć sprawdzenie.

Ponowne próby

Jeśli Twój punkt końcowy nie zwróci kodu statusu 2xx (lub przekroczy czas — limit czasu dostawy to 10s), Smart Money API ponawia próbę do 3 razy z wykładniczym wycofywaniem (około 1s, 4s, potem 16s). Uczyń swój handler idempotentnym, aby ponownie dostarczone zdarzenie można było bezpiecznie przetworzyć dwukrotnie.

Webhooki przychodzące (TradingView)

Osobno możesz wysłać do nas przychodzące powiadomienie. POST /v1/tradingview/webhook odbiera alert TradingView, przetwarza go przez /confirmi zwraca potwierdzenie. Ponieważ TradingView nie może wysyłać niestandardowych nagłówków, uwierzytelnia się za pomocą pola secret w ciele JSON (nie X-API-Key). Wyślij secret, symboli direction (long/short); opcjonalnie timeframe, strategyi price.

Gotowy na podłączenie sygnałów w czasie rzeczywistym?

Uzyskaj klucz API