ওয়েবহুক বাস্তবায়ন নির্দেশিকা

একটি HTTPS URL নিবন্ধন করুন এবং রিয়েল-টাইম, HMAC-সাইনড ইভেন্ট পুশ পান যখন স্মার্ট-মানি সিগন্যাল ফায়ার করে — কোন পোলিং নেই। এই নির্দেশিকায় নিবন্ধন, ইভেন্ট ফিল্টারিং, সিগনেচার যাচাই এবং পুনরায় চেষ্টার আচরণ কভার করা হয়েছে।

ওভারভিউ

পোলিং করার পরিবর্তে /v1/confirm বা সিগন্যাল ফিড, একটি ওয়েবহুক নিবন্ধন করুন এবং Smart Money API একটি ইভেন্ট আপনার এন্ডপয়েন্টে POST করবে যখন একটি ম্যাচিং সিগন্যাল ফায়ার করে। প্রতিটি ডেলিভারি HMAC-SHA256 দিয়ে সাইনড থাকে যাতে আপনি যাচাই করতে পারেন যে এটি সত্যিই আমাদের কাছ থেকে এসেছে।

আউটবাউন্ড ওয়েবহুক উপলব্ধ আছে Pro এবং Enterprise প্ল্যানে।

একটি ওয়েবহুক নিবন্ধন করুন

POST করুন /v1/webhooks আপনার API কী সহ X-API-Key হেডারে। বডিতে চারটি ফিল্ড প্রয়োজন:

ফিল্ড	টাইপ	বিবরণ
url	string	ইভেন্ট পেতে HTTPS এন্ডপয়েন্ট (অবশ্যই শুরু হতে হবে `https://`)
events	array	পেতে ইভেন্টের নাম, যেমন `["HIGH","MEDIUM","VETO"]` বা `["*"]`
symbols	array	ফিল্টার করার জন্য সিম্বল, যেমন `["BTC","ETH"]` বা `["*"]`
secret	string	আপনার সাইনিং সিক্রেট — অন্তত ১৬টি অক্ষর। হ্যাশড সংরক্ষিত; সিগনেচার যাচাই করার জন্য আপনার পাশে কাঁচা মান রাখুন।

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"   # 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 রিসিভার)
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());
  // ... act on event ...
  res.status(200).end();
});

যাচাই করুন কাঁচা, আনপার্সড রিকোয়েস্ট বডির বিরুদ্ধে — পার্সড JSON পুনরায় সিরিয়ালাইজ করা বাইট অর্ডার বা স্পেসিং পরিবর্তন করতে পারে এবং চেক ভেঙে দিতে পারে।

পুনরায় চেষ্টা

যদি আপনার এন্ডপয়েন্ট একটি 2xx রিটার্ন না করে (বা টাইমআউট হয় — ডেলিভারি টাইমআউট 10s), Smart Money API এক্সপোনেনশিয়াল ব্যাকঅফ সহ 3 বার পর্যন্ত পুনরায় চেষ্টা করে (প্রায় 1s, 4s, তারপর 16s)। আপনার হ্যান্ডলার আইডেম্পোটেন্ট করুন যাতে একটি পুনরায় ডেলিভারড ইভেন্ট দুবার প্রসেস করা নিরাপদ।

ইনবাউন্ড ওয়েবহুক (TradingView)

আলাদাভাবে, আপনি একটি ইনবাউন্ড আমাদের কাছে অ্যালার্ট পাঠাতে পারেন। POST /v1/tradingview/webhook একটি TradingView অ্যালার্ট গ্রহণ করে, এটি চালায় /confirm, এবং কনফার্মেশন রিটার্ন করে। কারণ TradingView কাস্টম হেডার পাঠাতে পারে না, এটি JSON বডিতে একটি secret ফিল্ড দিয়ে অথেন্টিকেট করে (না X-API-Key)। পাঠান secret, symbol, এবং direction (long/short); ঐচ্ছিকভাবে timeframe, strategy, এবং price.

রিয়েল-টাইম সিগন্যাল সংযুক্ত করতে প্রস্তুত?

আপনার API কী পান