راهنمای پیاده‌سازی Webhook

یک URL HTTPS ثبت کنید و اعلان‌های رویداد بلادرنگ و امضا شده با HMAC را هنگام فعال شدن سیگنال‌های هوشمند دریافت کنید — بدون نیاز به پولینگ. این راهنما شامل ثبت، فیلتر کردن رویدادها، تأیید امضا و رفتار تلاش مجدد است.

مرور کلی

به جای پولینگ /v1/confirm یا فید سیگنال، یک وب‌هوک ثبت کنید و Smart Money API در لحظه فعال شدن یک سیگنال منطبق، یک رویداد را به نقطه پایان شما POST می‌کند. هر تحویل با HMAC-SHA256 امضا شده است تا بتوانید تأیید کنید که واقعاً از طرف ما ارسال شده است.

وب‌هوک‌های خروجی در طرح‌های Pro و Enterprise در دسترس هستند.

ثبت یک Webhook

POST به /v1/webhooks با کلید API خود در X-API-Key هدر. بدنه نیاز به چهار فیلد دارد:

فیلد	نوع	توضیحات
url	string	نقطه پایان 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 هگز از بدنه درخواست (به پایین مراجعه کنید)
Content-Type	`application/json`
User-Agent	`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"   # 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";

// کپچر کردن بدنه خام برای استفاده از بایت‌های دقیق در بررسی امضا.
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 ثانیه) تلاش می‌کند. هندلر خود را ایزوتوپ کنید تا پردازش مجدد یک رویداد ایمن باشد.

وب‌هوک‌های ورودی (TradingView)

به طور جداگانه، می‌توانید یک ورودی هشدار را برای ما ارسال کنید. POST /v1/tradingview/webhook یک هشدار TradingView را دریافت می‌کند، آن را از طریق /confirmعبور می‌دهد و تأیید را برمی‌گرداند. چون TradingView نمی‌تواند هدرهای سفارشی ارسال کند، از طریق یک secret فیلد در بدنه JSON احراز هویت می‌کند (نه X-API-Key). ارسال کنید secret, symbol، و direction (long/short); اختیاری timeframe, strategy، و price.

آماده اتصال سیگنال‌های لحظه‌ای هستید؟

کلید API خود را دریافت کنید