Webhook 實作指南
註冊一個 HTTPS URL，當聰明錢訊號觸發時接收即時且經過 HMAC 簽署的事件推送 — 無需輪詢。本指南涵蓋註冊、事件篩選、簽名驗證及重試行為。
概覽
取代輪詢 /v1/confirm 或訊號饋送，註冊一個 webhook，當符合條件的訊號觸發時，Smart Money API 會立即 POST 一個事件到你的端點。每次傳遞都使用 HMAC-SHA256 簽署，因此你可以驗證它確實來自我們。
外送 webhooks 適用於 專業版 和企業版方案。
註冊 Webhook
POST 至 /v1/webhooks 並在 X-API-Key 標頭中加入你的 API 金鑰。請求主體需包含四個欄位：
| 欄位 | 類型 | 描述 |
|---|
| url | 字串 | 接收事件的 HTTPS 端點 (必須以 https://) |
| events | 陣列 | 要接收的事件名稱，例如 ["HIGH","MEDIUM","VETO"] 或 ["*"] |
| symbols | 陣列 | 要篩選的標的，例如 ["BTC","ETH"] 或 ["*"] |
| secret | 字串 | 你的簽署密鑰 — 至少 16 個字元。儲存時會經過雜湊處理；請保留原始值以驗證簽名。 |
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"
}'
{
"webhook_id": 42,
"url": "https://yourapp.com/webhooks/smartmoney",
"events": ["HIGH", "MEDIUM"],
"symbols": ["BTC", "ETH"],
"message": "Webhook 註冊成功。使用 POST /v1/webhooks/test 進行測試"
}
事件篩選器
當事件名稱與標的符合你的註冊條件時，傳遞便會觸發。典型事件名稱是確認信心等級 — HIGH, MEDIUM, VETO — 加上通用的 SIGNAL 事件。使用 ["*"] 來接收所有事件或所有標的。
傳遞與標頭
每次傳遞都是一個 HTTP POST 帶有 JSON 主體及以下標頭：
| 標頭 | 數值 |
|---|
| X-SmartMoney-事件 | 事件名稱（例如 HIGH) |
| X-SmartMoney-簽名 | 請求主體的HMAC-SHA256十六進位摘要（見下方說明） |
| 內容類型 | application/json |
| 用戶代理 | SmartMoneyAPI-Webhook/1.0 |
{
"event": "HIGH",
"ts": "2026-07-01T18:22:05Z",
"symbol": "BTC",
"direction": "long",
"confidence": "HIGH",
"composite": 0.74,
"webhook_id": 42
}
回應任意 2xx 狀態碼表示接收成功。非2xx狀態碼（或逾時）將觸發重試。
驗證簽名
簽名位於 X-SmartMoney-Signature 是請求主體的 HMAC-SHA256 十六進位摘要。 HMAC 金鑰是您註冊時設定的密鑰經 SHA-256 十六進位摘要後的結果 （您的原始密鑰在我們端僅以雜湊形式儲存）。驗證方式：推導出金鑰，對原始主體進行 HMAC 運算，並透過恆定時間檢查比對。任何驗證失敗的請求都應拒絕。
import hashlib, hmac
from flask import Flask, request, abort
app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars" # 您註冊時設定的值
@app.post("/webhooks/smartmoney")
def receive():
raw = request.get_data() # 主體的原始位元組
sig = request.headers.get("X-SmartMoney-Signature", "")
key = hashlib.sha256(MY_SECRET.encode()).hexdigest() # HMAC 金鑰 = sha256(密鑰) 十六進位
expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig):
abort(401)
event = request.get_json()
# ... 根據 event["event"], event["symbol"], event["composite"] 執行操作 ...
return "", 200
import crypto from "crypto";
import express from "express";
const app = express();
const MY_SECRET = "a-long-random-secret-16-plus-chars";
// 擷取原始請求體以確保簽名校驗使用完全相同的位元組。
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());
// ... 根據事件採取行動 ...
res.status(200).end();
});
對照 原始未解析的 請求主體進行驗證 — 重新序列化已解析的 JSON 可能改變位元組順序或間距，導致校驗失敗。
重試機制
若您的端點未返回 2xx （或超時 — 交付超時時間為10秒），Smart Money API 會以指數退避方式重試最多3次（約1秒、4秒，然後16秒）。請確保您的處理程序具有冪等性，以便安全地處理重新傳送的事件。
入站 Webhooks（TradingView）
另外，您可以發送一個 入站 警報給我們。 POST /v1/tradingview/webhook 接收 TradingView 警報，通過 /confirm運行它，並返回確認。由於 TradingView 無法發送自定義標頭，它通過 JSON 主體中的 secret 字段進行身份驗證（非 X-API-Key）。發送 secret, symbol，和 direction (long/short）；可選地 timeframe, strategy，和 price.