دليل تنفيذ Webhook

سجل عنوان URL لـ HTTPS واستقبل دفع الأحداث الموقعة بـ HMAC في الوقت الفعلي عند تنشيط إشارات Smart Money — بدون استطلاع. يغطي هذا الدليل التسجيل، تصفية الأحداث، التحقق من التوقيع، وسلوك إعادة المحاولة.

نظرة عامة

بدلاً من الاستطلاع /v1/confirm أو تغذية الإشارة، سجل webhook وسيقوم Smart Money API بنشر حدث إلى نقطة نهايتك لحظة تنشيط إشارة مطابقة. كل تسليم موقّع بـ HMAC-SHA256 حتى تتمكن من التحقق من أنه جاء منا حقًا.

تتوفر webhooks الصادرة على 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 للجسم الخام، وقارن مع فحص ثابت الوقت. ارفض أي طلب يفشل.

Python (متلقٍ Flask)
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(secret) hex
    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

Node.js (متلقٍ Express)
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());
  // ... تصرف بناءً على event ...
  res.status(200).end();
});

تحقق ضد الجسم الخام، غير المحلل للطلب — إعادة تسلسل JSON المحلل يمكن أن يغير ترتيب البايتات أو المسافات ويكسر الفحص.

إعادة المحاولة

إذا لم ترد نقطة نهايتك بـ 2xx (أو انتهت المهلة — مهلة التسليم هي 10 ثوانٍ)، يقوم Smart Money API بإعادة المحاولة حتى 3 مرات مع تراجع أسي (حوالي 1 ثانية، 4 ثوانٍ، ثم 16 ثانية). اجعل معالجك غير متغير بحيث يمكن معالجة الحدث المعاد تسليمه بأمان مرتين.

Webhooks الواردة (TradingView)

بشكل منفصل، يمكنك إرسال وارد تنبيه إلينا. POST /v1/tradingview/webhook يستقبل تنبيه TradingView، يعالجه عبر /confirm، ويعيد التأكيد. لأن TradingView لا يمكنه إرسال رؤوس مخصصة، فإنه يتم المصادقة عبر secret حقل في جسم JSON (ليس X-API-Key). أرسل secret, symbol، و direction (long/short)؛ اختياريًا timeframe, strategy، و price.

هل أنت مستعد لربط إشارات الوقت الفعلي؟

احصل على مفتاح API الخاص بك