Panduan Pelaksanaan Webhook

Daftar URL HTTPS dan terima pemberitahuan acara masa nyata yang ditandatangani HMAC apabila isyarat wang pintar dicetuskan — tiada pengundian. Panduan ini meliputi pendaftaran, penapisan acara, pengesahan tandatangan, dan tingkah laku percubaan semula.

Gambaran Keseluruhan

Daripada mengundi /v1/confirm atau suapan isyarat, daftar webhook dan Smart Money API akan POST acara ke titik akhir anda sebaik sahaja isyarat yang sepadan dicetuskan. Setiap penghantaran ditandatangani dengan HMAC-SHA256 supaya anda boleh mengesahkan ia benar-benar datang dari kami.

Webhook keluar tersedia pada Pro dan pelan Enterprise.

Daftar Webhook

POST ke /v1/webhooks dengan kunci API anda dalam X-API-Key tajuk. Badan memerlukan empat medan:

Medan	Jenis	Penerangan
url	string	Titik akhir HTTPS untuk menerima acara (mesti bermula dengan `https://`)
events	array	Nama acara untuk diterima, contohnya `["HIGH","MEDIUM","VETO"]` atau `["*"]`
symbols	array	Simbol untuk ditapis, contohnya `["BTC","ETH"]` atau `["*"]`
secret	string	Rahsia tandatangan anda — sekurang-kurangnya 16 aksara. Disimpan sebagai hash; simpan nilai mentah di pihak anda untuk mengesahkan tandatangan.

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

Penapis Acara

Penghantaran dicetuskan untuk acara yang nama dan simbolnya sepadan dengan pendaftaran anda. Nama acara biasa ialah baldi keyakinan pengesahan — HIGH, MEDIUM, VETO — tambah acara SIGNAL generik. Gunakan ["*"] untuk menerima semua acara atau semua simbol.

Penghantaran & Tajuk

Setiap penghantaran adalah HTTP POST dengan badan JSON dan tajuk berikut:

Tajuk	Nilai
X-SmartMoney-Event	Nama acara (contohnya `HIGH`)
X-SmartMoney-Signature	HMAC-SHA256 hex digest badan permintaan (lihat di bawah)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Balas dengan sebarang 2xx status untuk mengakui. Bukan 2xx (atau masa tamat) mencetuskan percubaan semula.

Pengesahan Tandatangan

Tandatangan dalam X-SmartMoney-Signature adalah HMAC-SHA256 hex digest badan permintaan. Kunci HMAC ialah SHA-256 hex digest rahsia yang anda daftarkan (rahsia mentah anda hanya disimpan sebagai hash di pihak kami). Untuk mengesahkan: dapatkan kunci, HMAC badan mentah, dan bandingkan dengan semakan masa tetap. Tolak sebarang permintaan yang gagal.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # nilai yang anda daftarkan

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # bait tepat badan
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # Kunci HMAC = sha256(rahsia) hex
    expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # ... bertindak berdasarkan event["event"], event["symbol"], event["composite"] ...
    return "", 200

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

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

// Tangkap badan mentah supaya semakan tandatangan menggunakan bait tepat.
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());
  // ... bertindak berdasarkan event ...
  res.status(200).end();
});

Sahkan terhadap badan permintaan mentah, tidak dihuraikan — penyusunan semula JSON yang dihuraikan boleh mengubah susunan bait atau jarak dan memecahkan semakan.

Percubaan Semula

Jika titik akhir anda tidak mengembalikan 2xx (atau masa tamat — masa tamat penghantaran ialah 10s), Smart Money API akan mencuba semula sehingga 3 kali dengan backoff eksponen (lebih kurang 1s, 4s, kemudian 16s). Buat pengendali anda idempoten supaya acara yang dihantar semula selamat diproses dua kali.

Webhook Masuk (TradingView)

Secara berasingan, anda boleh menghantar masuk amaran kepada kami. POST /v1/tradingview/webhook menerima amaran TradingView, menjalankannya melalui /confirm, dan mengembalikan pengesahan. Oleh kerana TradingView tidak boleh menghantar tajuk tersuai, ia mengesahkan melalui secret medan dalam badan JSON (bukan X-API-Key). Hantar secret, symbol, dan direction (long/short); pilihan timeframe, strategy, dan price.

Sedia untuk menyambung isyarat masa nyata?

Dapatkan kunci API anda