Webhook Integration Setup

Webhooks enable real-time event notifications without polling. Smart Money API sends HTTP POST requests to your endpoint when significant events occur: whale movements, exchange flow changes, miner activity, and market signals. This guide covers webhook configuration, event types, and retry logic.

Webhook Guide

Setting Up Webhooks
Supported Event Types
Webhook Payload Format
Signature Verification
Retry and Timeout Logic
Error Handling
Implementation Examples

Setting Up Webhooks

Configure webhooks in your account dashboard at Dashboard → Webhooks → Add Endpoint. Provide your HTTPS endpoint URL and select event types to monitor.

Webhook requirements:

HTTPS endpoint (TLS 1.2+)
Responds within 30 seconds
Returns HTTP 200-299 status code
Can receive 100+ concurrent requests during high-activity periods
Idempotent processing (handles duplicate events)

Supported Event Types

Available webhook events cover major market signals:

whale.movement: Major wallet transaction detected
whale.accumulation_surge: Multiple whales accumulating simultaneously
exchange.inflow_spike: Sudden exchange deposit increase
exchange.outflow_surge: Major withdrawal wave detected
miner.capitulation: Miner selling activity above threshold
miner.accumulation: Miners holding coins (bullish signal)
metric.nvt_signal: NVT ratio enters overbought/oversold zone
metric.mvrv_extreme: MVRV ratio indicates potential reversal

Webhook Payload Format

        JSON
      

{
  "event_id": "evt_1234567890",
  "event_type": "whale.movement",
  "timestamp": "2026-03-21T14:30:00Z",
  "signature": "sha256=abcd1234...",
  "data": {
    "address": "1A1z7agoat...",
    "amount_btc": 125.5,
    "direction": "to_exchange",
    "whale_tier": "MEGA",
    "exchange": "binance",
    "price_at_event": 65432.10
  }
}
      

Signature Verification

All webhooks include an HMAC-SHA256 signature for verification. Validate signatures to ensure requests are from Smart Money API.

        PYTHON
      

import hmac
import hashlib
import json
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = 'your_webhook_secret'

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Get signature from header
    signature = request.headers.get('X-Webhook-Signature')

    # Get raw body
    raw_body = request.get_data()

    # Calculate expected signature
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    # Verify signature
    if not hmac.compare_digest(signature, expected):
        return {'error': 'Invalid signature'}, 401

    # Process webhook
    data = json.loads(raw_body)
    event_type = data['event_type']

    if event_type == 'whale.movement':
        handle_whale_movement(data['data'])
    elif event_type == 'exchange.inflow_spike':
        handle_inflow_spike(data['data'])

    return {'status': 'received'}, 200

def handle_whale_movement(data):
    print(f"Whale movement: {data['amount_btc']} BTC to {data['direction']}")

app.run()
      

Retry and Timeout Logic

If your endpoint fails to respond, Smart Money API retries with exponential backoff: 1s, 5s, 30s, 5m, 30m, then stops. Always implement idempotent processing using event_id.

Error Handling

Handle webhooks gracefully:

Return 200 immediately after queueing for processing
Don't perform long operations in webhook handler
Log all webhook activity for debugging
Implement backpressure mechanisms if overwhelmed
Alert on webhook delivery failures

Important: Process webhooks asynchronously using message queues (RabbitMQ, Kafka) for production reliability and scalability.