Руководство по реализации Webhook

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

Обзор

Вместо опроса /v1/confirm или ленты сигналов, зарегистрируйте webhook, и Smart Money API отправит POST-запрос с событием на ваш endpoint в момент срабатывания соответствующего сигнала. Каждая доставка подписана с помощью HMAC-SHA256, чтобы вы могли убедиться, что она действительно пришла от нас.

Исходящие webhook доступны на тарифах Pro и Enterprise.

Регистрация Webhook

Отправьте POST-запрос на /v1/webhooks с вашим API-ключом в заголовке X-API-Key . Тело запроса должно содержать четыре поля:

Поле	Тип	Описание
url	string	HTTPS endpoint для получения событий (должен начинаться с `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 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 может изменить порядок байтов или пробелы и нарушить проверку.

Повторные попытки

Если ваш endpoint не возвращает 2xx (или происходит таймаут — время ожидания доставки составляет 10 секунд), Smart Money API повторяет попытку до 3 раз с экспоненциальной задержкой (примерно 1с, 4с, затем 16с). Сделайте ваш обработчик идемпотентным, чтобы повторно доставленное событие можно было безопасно обработать дважды.

Входящие Webhook (TradingView)

Отдельно вы можете отправить входящее уведомление нам. POST /v1/tradingview/webhook получает уведомление TradingView, пропускает его через /confirmи возвращает подтверждение. Поскольку TradingView не может отправлять пользовательские заголовки, аутентификация происходит через secret поле в теле JSON (не X-API-Key). Отправьте secret, symbol, и direction (long/short); опционально timeframe, strategy, и price.

Готовы подключить сигналы в реальном времени?

Получите ваш API-ключ