Guia de Implementação de Webhook

Registre um URL HTTPS e receba notificações de eventos em tempo real, assinadas com HMAC, quando os sinais de smart-money forem acionados — sem necessidade de polling. Este guia aborda registro, filtragem de eventos, verificação de assinatura e comportamento de tentativas de reenvio.

Visão Geral

Em vez de polling /v1/confirm ou o feed de sinais, registre um webhook e a Smart Money API enviará um evento POST para o seu endpoint no momento em que um sinal correspondente for acionado. Cada entrega é assinada com HMAC-SHA256 para que você possa verificar se realmente veio de nós.

Webhooks de saída estão disponíveis nos planos Pro e Enterprise.

Registrar um Webhook

Envie um POST para /v1/webhooks com sua chave de API no cabeçalho X-API-Key O corpo precisa de quatro campos:

Campo	Tipo	Descrição
url	string	Endpoint HTTPS para receber eventos (deve começar com `https://`)
events	array	Nomes de eventos a receber, por exemplo `["HIGH","MEDIUM","VETO"]` ou `["*"]`
symbols	array	Símbolos para filtrar, por exemplo `["BTC","ETH"]` ou `["*"]`
secret	string	Seu segredo de assinatura — pelo menos 16 caracteres. Armazenado como hash; mantenha o valor original do seu lado para verificar assinaturas.

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 registrado. Teste com POST /v1/webhooks/test"
}

Filtros de Eventos

As entregas são acionadas para eventos cujo nome e símbolo correspondam ao seu registro. Os nomes típicos de eventos são os níveis de confirmação — HIGH, MEDIUM, VETO — além de eventos genéricos SIGNAL Use ["*"] para receber todos os eventos ou todos os símbolos.

Entrega & Cabeçalhos

Cada entrega é um HTTP POST com um corpo JSON e estes cabeçalhos:

Cabeçalho	Valor
X-SmartMoney-Event	O nome do evento (por exemplo `HIGH`)
X-SmartMoney-Signature	Digest HMAC-SHA256 em hexadecimal do corpo da requisição (veja abaixo)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Responda com qualquer 2xx status para confirmar. Um status não-2xx (ou um timeout) aciona uma tentativa de reenvio.

Verificação de Assinaturas

A assinatura em X-SmartMoney-Signature é um digest HMAC-SHA256 em hexadecimal do corpo da requisição. A chave HMAC é o digest SHA-256 em hexadecimal do segredo que você registrou (seu segredo original é armazenado apenas como hash do nosso lado). Para verificar: derive a chave, aplique HMAC ao corpo bruto e compare com uma verificação em tempo constante. Rejeite qualquer requisição que falhe.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # o valor que você registrou

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # bytes exatos do corpo
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # chave HMAC = sha256(segredo) em hex
    expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # ... aja com base em event["event"], event["symbol"], event["composite"] ...
    return "", 200

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

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

// Capture o corpo bruto para que a verificação de assinatura use os bytes exatos.
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());
  // ... aja com base no evento ...
  res.status(200).end();
});

Verifique com base no corpo bruto, não analisado da requisição — re-serializar um JSON analisado pode alterar a ordem dos bytes ou espaçamento e quebrar a verificação.

Tentativas de Reenvio

Se o seu endpoint não retornar um 2xx (ou atingir timeout — o tempo limite de entrega é de 10s), a Smart Money API tentará reenviar até 3 vezes com backoff exponencial (aproximadamente 1s, 4s, depois 16s). Torne seu manipulador idempotente para que um evento reenviado possa ser processado novamente com segurança.

Webhooks de Entrada (TradingView)

Separadamente, você pode enviar um alerta de entrada para nós. POST /v1/tradingview/webhook recebe um alerta do TradingView, processa-o através do /confirme retorna a confirmação. Como o TradingView não pode enviar cabeçalhos personalizados, ele autentica via um campo secret no corpo JSON (não X-API-Key). Envie secret, symbole direction (long/short); opcionalmente timeframe, strategye price.

Pronto para configurar sinais em tempo real?

Obtenha sua chave de API