Panduan Implementasi Webhook

Daftarkan URL HTTPS dan terima notifikasi acara real-time yang ditandatangani HMAC saat sinyal smart-money terpicu — tanpa polling. Panduan ini mencakup pendaftaran, penyaringan acara, verifikasi tanda tangan, dan perilaku percobaan ulang.

Ikhtisar

Alih-alih melakukan polling /v1/confirm atau umpan sinyal, daftarkan webhook dan Smart Money API akan mengirimkan POST acara ke endpoint Anda saat sinyal yang sesuai terpicu. Setiap pengiriman ditandatangani dengan HMAC-SHA256 sehingga Anda dapat memverifikasi bahwa itu benar-benar berasal dari kami.

Webhook keluar tersedia di paket Pro dan Enterprise.

Daftarkan Webhook

POST ke /v1/webhooks dengan kunci API Anda di X-API-Key header. Body memerlukan empat bidang:

Bidang	Tipe	Deskripsi
url	string	Endpoint HTTPS untuk menerima acara (harus dimulai dengan `https://`)
events	array	Nama acara yang akan diterima, misalnya `["HIGH","MEDIUM","VETO"]` atau `["*"]`
symbols	array	Simbol untuk disaring, misalnya `["BTC","ETH"]` atau `["*"]`
secret	string	Rahasia tanda tangan Anda — minimal 16 karakter. Disimpan dalam bentuk hash; simpan nilai mentah di sisi Anda untuk memverifikasi tanda tangan.

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 terdaftar. Uji dengan POST /v1/webhooks/test"
}

Filter Acara

Pengiriman terpicu untuk acara yang nama dan simbolnya sesuai dengan pendaftaran Anda. Nama acara umumnya adalah bucket kepercayaan konfirmasi — HIGH, MEDIUM, VETO — ditambah acara SIGNAL generik. Gunakan ["*"] untuk menerima semua acara atau semua simbol.

Pengiriman & Header

Setiap pengiriman adalah HTTP POST dengan body JSON dan header berikut:

Header	Nilai
X-SmartMoney-Event	Nama acara (misalnya `HIGH`)
X-SmartMoney-Signature	Digest heksa HMAC-SHA256 dari body permintaan (lihat di bawah)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Tanggapi dengan status 2xx apa pun untuk mengonfirmasi. Non-2xx (atau timeout) memicu percobaan ulang.

Verifikasi Tanda Tangan

Tanda tangan di X-SmartMoney-Signature adalah digest heksa HMAC-SHA256 dari body permintaan. Kunci HMAC adalah digest heksa SHA-256 dari rahasia yang Anda daftarkan (rahasia mentah Anda hanya disimpan dalam bentuk hash di sisi kami). Untuk memverifikasi: turunkan kunci, HMAC body mentah, dan bandingkan dengan pemeriksaan waktu-konstan. Tolak permintaan yang gagal.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # nilai yang Anda daftarkan

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # byte tepat dari body
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # Kunci HMAC = sha256(secret) heksa
    expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # ... tindakan berdasarkan event["event"], event["symbol"], event["composite"] ...
    return "", 200

Node.js (Penerima Express)
import crypto from "crypto";
import express from "express";

const app = express();
const MY_SECRET = "a-long-random-secret-16-plus-chars";

// Tangkap body mentah sehingga pemeriksaan tanda tangan menggunakan byte yang tepat.
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());
  // ... tindakan berdasarkan event ...
  res.status(200).end();
});

Verifikasi terhadap body permintaan mentah, tidak diurai — serialisasi ulang JSON yang diurai dapat mengubah urutan byte atau spasi dan merusak pemeriksaan.

Percobaan Ulang

Jika endpoint Anda tidak mengembalikan 2xx (atau timeout — timeout pengiriman adalah 10s), Smart Money API akan mencoba ulang hingga 3 kali dengan backoff eksponensial (sekitar 1s, 4s, lalu 16s). Buat handler Anda idempoten sehingga acara yang dikirim ulang aman untuk diproses dua kali.

Webhook Masuk (TradingView)

Secara terpisah, Anda dapat mengirim masuk peringatan kepada kami. POST /v1/tradingview/webhook menerima peringatan TradingView, menjalankannya melalui /confirm, dan mengembalikan konfirmasi. Karena TradingView tidak dapat mengirim header khusus, itu diautentikasi melalui secret bidang dalam body JSON (bukan X-API-Key). Kirim secret, symbol, dan direction (long/short); opsional timeframe, strategy, dan price.

Siap menghubungkan sinyal real-time?

Dapatkan kunci API Anda