Посібник з реалізації вебхуків

Зареєструйте HTTPS URL та отримуйте сповіщення про події в реальному часі з підписом HMAC, коли спрацьовують сигнали smart-money — без опитування. Цей посібник охоплює реєстрацію, фільтрацію подій, перевірку підписів та поведінку при повторних спробах.

Огляд

Замість опитування /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	Ваш секретний ключ для підпису — не менше 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 hex-дайджест тіла запиту (див. нижче)
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 hex-дайджест тіла запиту. Ключ HMAC — це SHA-256 hex-дайджест секрету, який ви зареєстрували (ваш необроблений секрет зберігається лише у хешованому вигляді на нашому боці). Для перевірки: отримайте ключ, обчисліть HMAC для необробленого тіла та порівняйте з постійною перевіркою часу. Відхиляйте будь-який запит, який не пройшов перевірку.

Python (Flask receiver)
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";

// 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 (або виникає тайм-аут — час очікування доставки становить 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-ключ