Real-time whale webhooks signed HMAC-SHA256

Home › API docs › Real-time webhooks · Updated 2026-10-26

Endpoint

Base URL https://deepbluealpha.io · JSON over HTTPS · Ethereum mainnet only.

Endpoint filters (set in your account)

Example request (curl)

# Send yourself a signed test event from the account page ("Send test"),
# or reproduce a signature locally to test your receiver:
BODY='{"event_id":"test_1","type":"test"}'
TS=$(date +%s)
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$DBA_WEBHOOK_SECRET" -hex | sed 's/^.* //')
curl -s -X POST http://localhost:8000/dba-webhook \
  -H "Content-Type: application/json" \
  -H "X-DBA-Signature: t=$TS,v1=$SIG" -d "$BODY"

Python example

# pip install fastapi uvicorn
import hashlib, hmac, json, os, time
from fastapi import FastAPI, Request, Response

SECRET = os.environ["DBA_WEBHOOK_SECRET"]          # whsec_...
app = FastAPI()
seen: set[str] = set()                             # use a DB/Redis in production

def verify(body: bytes, header: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        ts, sig = int(parts["t"]), parts["v1"]
    except (ValueError, KeyError):
        return False
    if abs(time.time() - ts) > tolerance:
        return False
    want = hmac.new(SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sig)

@app.post("/dba-webhook")
async def dba_webhook(request: Request):
    body = await request.body()                    # raw bytes, before parsing
    if not verify(body, request.headers.get("X-DBA-Signature", "")):
        return Response(status_code=401)
    event = json.loads(body)
    if event["event_id"] in seen:                  # retries can repeat an event
        return Response(status_code=200)
    seen.add(event["event_id"])
    if event.get("type") == "whale_move":
        print(event["time_utc"], event["token"], event["flow"],
              f'${event["usd_value"]:,.0f}', event["exchange"] or "DEX")
    return Response(status_code=200)               # reply 2xx within 10 seconds

# run: uvicorn receiver:app --port 8000

Event body (POST to your endpoint) EXAMPLE VALUES

{
  "type": "whale_move",
  "event_id": "mv_10000002",
  "api_version": "2026-10-16",
  "time_utc": "2026-01-01T12:00:00Z",
  "tx_hash": "0x8b85…2b93",
  "wallet": "0x83d8…e09e",
  "token": "LINK",
  "action": "CEX_WITHDRAW",
  "usd_value": 412500.0,
  "venue_type": "exchange",
  "exchange": "Binance",
  "flow": "withdrawn_from_exchange"
}

Field names and structure are the real ones; the numbers, hashes and addresses are placeholders, not live data.

Fields

Notes and limits

• Check the signature on the raw bytes before parsing JSON, and reject timestamps older than 5 minutes.
• Events can arrive out of order and, rarely, more than once: de-duplicate on event_id and order on time_utc. Moves filled in after the fact can arrive minutes or hours late.
• Endpoints must be public HTTPS addresses; redirects are not followed; private, loopback and internal addresses are refused. Each webhook keeps a 7-day delivery log in your account.
• Missed events (downtime, a paused endpoint) are in the daily data files, the complete record.
• Personal plans (Pro and up) have a different feature: alert webhooks (Discord, Slack or a custom URL) for the alert types you choose, not this every-move feed.

Errors

• 401 (your reply) — Return 401 when the signature fails; we count non-2xx as a failed delivery and retry.
• 3xx — Treated as a failure: redirects are not followed.

FAQ

Is there a real-time whale transaction webhook API for Ethereum?

Yes. The Deep Blue Alpha Business plan ($299/mo or $2,990/yr) sends one HMAC-SHA256-signed JSON POST for every new move by 20,000+ tracked Ethereum whale wallets, filtered by coin, move type and minimum USD size, to up to 3 HTTPS endpoints, with retries.

How to verify a Deep Blue Alpha webhook signature?

Read X-DBA-Signature (t=<unix>,v1=<hex>), compute HMAC-SHA256 with your whsec_ secret over the string "<t>." followed by the raw request body, compare in constant time, and reject timestamps older than 5 minutes.

More endpoint docs

Guides: best Ethereum whale tracking APIs compared · real-time whale tracking for a trading bot · whale webhook APIs · methodology · OpenAPI 3.0 spec · Business plan