Guía de Implementación de Webhook

Registra una URL HTTPS y recibe notificaciones de eventos en tiempo real firmadas con HMAC cuando se activen señales de smart-money — sin necesidad de polling. Esta guía cubre registro, filtrado de eventos, verificación de firmas y comportamiento de reintentos.

Resumen

En lugar de hacer polling /v1/confirm o consultar el feed de señales, registra un webhook y Smart Money API enviará un evento POST a tu endpoint en el momento en que se active una señal coincidente. Cada entrega está firmada con HMAC-SHA256 para que puedas verificar que proviene de nosotros.

Los webhooks salientes están disponibles en los planes Pro y Enterprise.

Registrar un Webhook

Envía un POST a /v1/webhooks con tu clave API en el encabezado X-API-Key El cuerpo debe incluir cuatro campos:

Campo	Tipo	Descripción
url	string	Endpoint HTTPS para recibir eventos (debe comenzar con `https://`)
events	array	Nombres de eventos a recibir, ej. `["HIGH","MEDIUM","VETO"]` o `["*"]`
symbols	array	Símbolos para filtrar, ej. `["BTC","ETH"]` o `["*"]`
secret	string	Tu secreto de firma — mínimo 16 caracteres. Se almacena hasheado; guarda el valor original en tu lado para verificar firmas.

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. Prueba con POST /v1/webhooks/test"
}

Filtros de Eventos

Las entregas se activan para eventos cuyo nombre y símbolo coincidan con tu registro. Los nombres típicos de eventos son los niveles de confianza de confirmación — HIGH, MEDIUM, VETO — además de eventos genéricos SIGNAL . Usa ["*"] para recibir todos los eventos o todos los símbolos.

Entrega y Encabezados

Cada entrega es un HTTP POST con un cuerpo JSON y estos encabezados:

Encabezado	Valor
X-SmartMoney-Event	El nombre del evento (ej. `HIGH`)
X-SmartMoney-Signature	Resumen HMAC-SHA256 en hexadecimal del cuerpo de la solicitud (ver abajo)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Responde con cualquier 2xx estado para confirmar. Un código no 2xx (o un timeout) activa un reintento.

Verificación de Firmas

La firma en X-SmartMoney-Signature es un resumen HMAC-SHA256 en hexadecimal del cuerpo de la solicitud. La clave HMAC es el resumen SHA-256 en hexadecimal del secreto que registraste (tu secreto original solo se almacena hasheado en nuestro lado). Para verificar: deriva la clave, aplica HMAC al cuerpo original y compara con una verificación de tiempo constante. Rechaza cualquier solicitud que falle.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # el valor que registraste

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # bytes exactos del cuerpo
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # clave HMAC = sha256(secreto) en hex
    expected = hmac.new(key.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    # ... actúa según 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";

// Captura el cuerpo original para que la verificación use los bytes exactos.
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úa según event ...
  res.status(200).end();
});

Verifica contra el cuerpo original, sin analizar de la solicitud — volver a serializar JSON analizado puede cambiar el orden de bytes o espacios y romper la verificación.

Reintentos

Si tu endpoint no devuelve un 2xx (o hay un timeout — el timeout de entrega es de 10s), Smart Money API reintenta hasta 3 veces con retroceso exponencial (aproximadamente 1s, 4s, luego 16s). Haz que tu manejador sea idempotente para que un evento reenviado sea seguro de procesar dos veces.

Webhooks Entrantes (TradingView)

Por separado, puedes enviar una alerta entrante a nosotros. POST /v1/tradingview/webhook recibe una alerta de TradingView, la procesa a través de /confirmy devuelve la confirmación. Como TradingView no puede enviar encabezados personalizados, se autentica mediante un campo secret en el cuerpo JSON (no X-API-Key). Envía secret, symboly direction (long/short); opcionalmente timeframe, strategyy price.

¿Listo para conectar señales en tiempo real?

Obtén tu clave API