Hướng dẫn Triển khai Webhook

Đăng ký URL HTTPS và nhận các thông báo sự kiện được ký HMAC đẩy thời gian thực khi các tín hiệu smart-money kích hoạt — không cần polling. Hướng dẫn này bao gồm đăng ký, lọc sự kiện, xác minh chữ ký và hành vi thử lại.

Tổng quan

Thay vì polling /v1/confirm hoặc nguồn cấp tín hiệu, hãy đăng ký webhook và Smart Money API sẽ POST một sự kiện đến điểm cuối của bạn ngay khi một tín hiệu phù hợp kích hoạt. Mỗi lần giao nhận đều được ký bằng HMAC-SHA256 để bạn có thể xác minh rằng nó thực sự đến từ chúng tôi.

Webhook gửi đi có sẵn trên các gói Pro và Enterprise.

Đăng ký Webhook

POST đến /v1/webhooks với khóa API của bạn trong X-API-Key tiêu đề. Phần thân cần bốn trường:

Trường	Loại	Mô tả
url	chuỗi	Điểm cuối HTTPS để nhận sự kiện (phải bắt đầu bằng `https://`)
events	mảng	Tên sự kiện để nhận, ví dụ `["HIGH","MEDIUM","VETO"]` hoặc `["*"]`
symbols	mảng	Các ký hiệu để lọc, ví dụ `["BTC","ETH"]` hoặc `["*"]`
secret	chuỗi	Bí mật ký của bạn — ít nhất 16 ký tự. Được lưu trữ dưới dạng băm; giữ giá trị thô ở phía bạn để xác minh chữ ký.

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 đã đăng ký. Kiểm tra với POST /v1/webhooks/test"
}

Bộ lọc Sự kiện

Các lần giao nhận kích hoạt cho các sự kiện có tên và ký hiệu khớp với đăng ký của bạn. Tên sự kiện điển hình là các nhóm độ tin cậy xác nhận — HIGH, MEDIUM, VETO — cộng với các sự kiện SIGNAL chung. Sử dụng ["*"] để nhận tất cả sự kiện hoặc tất cả ký hiệu.

Giao nhận & Tiêu đề

Mỗi lần giao nhận là một HTTP POST với phần thân JSON và các tiêu đề sau:

Tiêu đề	Giá trị
X-SmartMoney-Event	Tên sự kiện (ví dụ `HIGH`)
X-SmartMoney-Signature	Chuỗi hex HMAC-SHA256 của phần thân yêu cầu (xem bên dưới)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Phản hồi với bất kỳ 2xx trạng thái nào để xác nhận. Non-2xx (hoặc thời gian chờ) sẽ kích hoạt thử lại.

Xác minh Chữ ký

Chữ ký trong X-SmartMoney-Signature là một chuỗi hex HMAC-SHA256 của phần thân yêu cầu. Khóa HMAC là chuỗi hex SHA-256 của bí mật bạn đã đăng ký (bí mật thô của bạn chỉ được lưu trữ dưới dạng băm ở phía chúng tôi). Để xác minh: tạo khóa, HMAC phần thân thô và so sánh với kiểm tra thời gian không đổi. Từ chối bất kỳ yêu cầu nào không đạt.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # giá trị bạn đã đăng ký

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # byte chính xác của phần thân
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # Khóa 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()
    # ... hành động trên 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());
  // ... hành động trên event ...
  res.status(200).end();
});

Xác minh với phần thân thô, chưa phân tích yêu cầu — việc tái tuần tự hóa JSON đã phân tích có thể thay đổi thứ tự byte hoặc khoảng cách và làm hỏng kiểm tra.

Thử lại

Nếu điểm cuối của bạn không trả về 2xx (hoặc thời gian chờ — thời gian chờ giao nhận là 10s), Smart Money API sẽ thử lại tối đa 3 lần với backoff theo cấp số nhân (khoảng 1s, 4s, sau đó 16s). Hãy làm cho trình xử lý của bạn idempotent để một sự kiện được giao lại có thể xử lý an toàn hai lần.

Webhook Đến (TradingView)

Riêng biệt, bạn có thể gửi một cảnh báo đến chúng tôi. POST /v1/tradingview/webhook nhận một cảnh báo TradingView, chạy nó qua /confirm, và trả về xác nhận. Vì TradingView không thể gửi tiêu đề tùy chỉnh, nó xác thực qua một secret trường trong phần thân JSON (không phải X-API-Key). Gửi secret, symbol, và direction (long/short); tùy chọn timeframe, strategy, và price.

Sẵn sàng kết nối các tín hiệu thời gian thực?

Nhận khóa API của bạn