Gabay sa Pagpapatupad ng Webhook

Magrehistro ng isang HTTPS URL at tumanggap ng mga push ng pangyayari sa real-time na may HMAC na lagda kapag nag-trigger ang mga smart-money signal — walang pag-poll. Saklaw ng gabay na ito ang pagrehistro, pag-filter ng pangyayari, pag-verify ng lagda, at pag-uugali ng pag-ulit.

Pangkalahatang-ideya

Sa halip na mag-poll /v1/confirm o ang signal feed, magrehistro ng webhook at ang Smart Money API ay magpo-POST ng isang pangyayari sa iyong endpoint sa sandaling mag-trigger ang isang katugmang signal. Ang bawat paghahatid ay may lagda na HMAC-SHA256 upang ma-verify mo na ito ay talagang galing sa amin.

Ang mga outbound webhook ay available sa Pro at Enterprise na mga plano.

Magrehistro ng Webhook

POST sa /v1/webhooks gamit ang iyong API key sa X-API-Key header. Kailangan ng katawan ng apat na field:

Field	Uri	Paglalarawan
url	string	HTTPS endpoint upang tumanggap ng mga pangyayari (dapat magsimula sa `https://`)
events	array	Mga pangalan ng pangyayari na tatanggapin, hal. `["HIGH","MEDIUM","VETO"]` o `["*"]`
symbols	array	Mga simbolo na ifilter, hal. `["BTC","ETH"]` o `["*"]`
secret	string	Ang iyong lihim na lagda — hindi bababa sa 16 na karakter. Naka-imbak na naka-hash; panatilihin ang raw na halaga sa iyong side upang ma-verify ang mga lagda.

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"
}

Mga Filter ng Pangyayari

Ang mga paghahatid ay nag-trigger para sa mga pangyayari na ang pangalan at simbolo ay tumutugma sa iyong rehistrasyon. Ang karaniwang mga pangalan ng pangyayari ay ang mga confidence bucket ng kumpirmasyon — HIGH, MEDIUM, VETO — kasama ang generic SIGNAL mga pangyayari. Gamitin ang ["*"] upang tumanggap ng lahat ng pangyayari o lahat ng simbolo.

Paghahatid & Mga Header

Ang bawat paghahatid ay isang HTTP POST na may JSON na katawan at mga header na ito:

Header	Halaga
X-SmartMoney-Event	Ang pangalan ng pangyayari (hal. `HIGH`)
X-SmartMoney-Signature	HMAC-SHA256 hex digest ng request body (tingnan sa ibaba)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Tumugon sa anumang 2xx status upang kumpirmahin. Ang non-2xx (o timeout) ay mag-trigger ng pag-ulit.

Pag-verify ng mga Lagda

Ang lagda sa X-SmartMoney-Signature ay isang HMAC-SHA256 hex digest ng request body. Ang HMAC key ay ang SHA-256 hex digest ng lihim na iyong nirehistro (ang iyong raw na lihim ay naka-imbak lang na naka-hash sa aming side). Upang ma-verify: kunin ang key, HMAC ang raw na katawan, at ihambing sa isang constant-time na check. Tanggihan ang anumang request na nabigo.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # ang halaga na iyong nirehistro

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # eksaktong bytes ng katawan
    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()
    # ... kumilos batay sa 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";

// Kunin ang raw na katawan upang ang signature check ay gumamit ng eksaktong 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());
  // ... kumilos batay sa event ...
  res.status(200).end();
});

I-verify laban sa raw, hindi na-parse request body — ang muling pag-serialize ng na-parse na JSON ay maaaring magbago ng byte order o spacing at masira ang check.

Mga Ulit

Kung ang iyong endpoint ay hindi nagbabalik ng 2xx (o nag-timeout — ang delivery timeout ay 10s), ang Smart Money API ay mag-uulit ng hanggang 3 beses na may exponential backoff (humigit-kumulang 1s, 4s, pagkatapos ay 16s). Gawing idempotent ang iyong handler upang ang muling na-deliver na pangyayari ay ligtas na iproseso nang dalawang beses.

Mga Papasok na Webhook (TradingView)

Hiwalay, maaari kang magpadala ng papasok alert sa amin. POST /v1/tradingview/webhook tumanggap ng TradingView alert, pinapatakbo ito sa pamamagitan ng /confirm, at ibabalik ang kumpirmasyon. Dahil ang TradingView ay hindi maaaring magpadala ng mga custom na header, ito ay nagpapatunay sa pamamagitan ng isang secret field sa JSON na katawan (hindi X-API-Key). Ipadala ang secret, symbol, at direction (long/short); opsyonal na timeframe, strategy, at price.

Handa nang i-wire up ang mga real-time na signal?

Kunin ang iyong API key