Webhook Implementatiehandleiding

Registreer een HTTPS-URL en ontvang real-time, HMAC-ondertekende gebeurtenismeldingen wanneer smart-money signalen worden geactiveerd — geen polling. Deze handleiding behandelt registratie, gebeurtenisfiltering, handtekeningverificatie en gedrag bij nieuwe pogingen.

Overzicht

In plaats van polling /v1/confirm of het signaal feed, registreer een webhook en Smart Money API zal een gebeurtenis POSTen naar je endpoint op het moment dat een overeenkomend signaal wordt geactiveerd. Elke levering is ondertekend met HMAC-SHA256 zodat je kunt verifiëren dat het echt van ons komt.

Uitgaande webhooks zijn beschikbaar op de Pro en Enterprise-abonnementen.

Registreer een Webhook

POST naar /v1/webhooks met je API-sleutel in de X-API-Key header. De body heeft vier velden nodig:

Veld	Type	Beschrijving
url	string	HTTPS-endpoint om gebeurtenissen te ontvangen (moet beginnen met `https://`)
events	array	Gebeurtenisnamen om te ontvangen, bijv. `["HIGH","MEDIUM","VETO"]` of `["*"]`
symbols	array	Symbolen om te filteren, bijv. `["BTC","ETH"]` of `["*"]`
secret	string	Jouw ondertekeningsgeheim — minimaal 16 tekens. Opgeslagen gehasht; bewaar de ruwe waarde aan jouw kant om handtekeningen te verifiëren.

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 geregistreerd. Test met POST /v1/webhooks/test"
}

Gebeurtenisfilters

Leveringen worden geactiveerd voor gebeurtenissen waarvan de naam en het symbool overeenkomen met je registratie. Typische gebeurtenisnamen zijn de bevestigingsbetrouwbaarheidsbuckets — HIGH, MEDIUM, VETO — plus generieke SIGNAL gebeurtenissen. Gebruik ["*"] om alle gebeurtenissen of alle symbolen te ontvangen.

Levering & Headers

Elke levering is een HTTP POST met een JSON-body en deze headers:

Header	Waarde
X-SmartMoney-Event	De gebeurtenisnaam (bijv. `HIGH`)
X-SmartMoney-Signature	HMAC-SHA256 hex digest van de request body (zie hieronder)
Content-Type	`application/json`
User-Agent	`SmartMoneyAPI-Webhook/1.0`

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

Reageer met een 2xx status om te bevestigen. Niet-2xx (of een timeout) triggert een nieuwe poging.

Handtekeningen Verifiëren

De handtekening in X-SmartMoney-Signature is een HMAC-SHA256 hex digest van de request body. De HMAC-sleutel is de SHA-256 hex digest van het geheim dat je hebt geregistreerd (je ruwe geheim wordt alleen gehashed aan onze kant opgeslagen). Om te verifiëren: leid de sleutel af, HMAC de ruwe body en vergelijk met een constante-tijd controle. Weiger elke aanvraag die faalt.

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

app = Flask(__name__)
MY_SECRET = "a-long-random-secret-16-plus-chars"   # de waarde die je hebt geregistreerd

@app.post("/webhooks/smartmoney")
def receive():
    raw = request.get_data()                        # exacte bytes van de body
    sig = request.headers.get("X-SmartMoney-Signature", "")
    key = hashlib.sha256(MY_SECRET.encode()).hexdigest()   # HMAC-sleutel = 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()
    # ... handel op 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";

// Vang de ruwe body op zodat de handtekeningcontrole de exacte bytes gebruikt.
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());
  // ... handel op event ...
  res.status(200).end();
});

Verifieer tegen de ruwe, niet-geparseerde request body — het opnieuw serialiseren van geparseerde JSON kan de bytevolgorde of spaties veranderen en de controle breken.

Nieuwe Pogingen

Als je endpoint geen 2xx retourneert (of een timeout heeft — de leveringstimeout is 10s), probeert Smart Money API tot 3 keer opnieuw met exponentiële backoff (ongeveer 1s, 4s, dan 16s). Maak je handler idempotent zodat een opnieuw geleverde gebeurtenis veilig twee keer kan worden verwerkt.

Inkomende Webhooks (TradingView)

Afzonderlijk kun je een inkomende alert naar ons sturen. POST /v1/tradingview/webhook ontvangt een TradingView alert, voert deze door /confirm, en retourneert de bevestiging. Omdat TradingView geen aangepaste headers kan sturen, wordt deze geauthenticeerd via een secret veld in de JSON-body (niet X-API-Key). Stuur secret, symbol, en direction (long/short); optioneel timeframe, strategy, en price.

Klaar om real-time signalen aan te sluiten?

Haal je API-sleutel op