Webhooks

​

Before you start

​

Choose event types

• live_sports_updated sends one pulse per game, and at most one every 20 seconds per game. A game going live or final is sent straight away. The game clock moving on its own never sends one. See Live game pulses.
• suspicious_trade_flagged and insider_radar_flag_raised are one event under two spellings. Subscribe with either name; listing both on one endpoint stores one. Your endpoint receives every delivery under the spelling it registered, in the x-0xinsider-event-type header and in the payload’s type, so an endpoint created before September 23, 2026 keeps receiving insider_radar_flag_raised.
• large_trades_inserted (and its older spelling whale_trades_inserted) carries a count of new large trades, not the trades themselves. Read the trades from Large trades.
• large_trade_inserted_v2 carries one trade per delivery. Set trade_filters when you create or update the endpoint to require a condition_id, wallet, minimum min_grade, or minimum min_size_usd; all supplied filters must match. grade is captured at publication and may be null, which never passes a minimum-grade filter. The delivery id stays stable across retries.
• large_trades_inserted and whale_trades_inserted, and trader_synced and whale_trader_synced, are each one event under two spellings, like the suspicious-trade pair below: an endpoint receives the spelling it registered.
• sharp_money_flow_detected and smart_money_flow_detected are also aliases. An endpoint receives the name it registered.
• The 4 export_job_* events go only to endpoints owned by the account that submitted the export.
• When paid access lapses, every queued delivery of a paid type moves to dead_letter with last_error set to delivery owner is no longer authorized for this event.

​

Create and verify your webhook

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Idempotency-Key: webhook-create-2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://api.yourapp.com/webhooks/0xinsider",
    "event_types": ["large_trades_inserted"]
  }' \
  "https://api.0xinsider.com/api/v1/webhooks"

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification_token": "whv_3c2e...redacted"}' \
  "https://api.0xinsider.com/api/v1/webhooks/42/verify"

• 422 with error.param url: your server answered outside 2xx, took longer than 10 seconds, or is not reachable from the public internet.
• 400 with error.param verification_token: the token is wrong or has expired. Delete the endpoint and create it again.

​

Receive a delivery

{
  "id": "evt_large_trades_inserted_rtds_9f2c...redacted",
  "type": "large_trades_inserted",
  "created_at": "2026-06-17T14:28:20Z",
  "data": { "count": 7 }
}

​

Live game pulses

{
  "id": "evt_live_sports_updated_nba-lal-bos-2026-09-22_pulse_14",
  "type": "live_sports_updated",
  "created_at": "2026-09-22T19:41:08Z",
  "data": {
    "event_slug": "nba-lal-bos-2026-09-22",
    "game_id": "20263",
    "league": "NBA",
    "version": 14,
    "changed": ["scores", "period"],
    "observed_at": "2026-09-22T19:41:07Z",
    "published_at": "2026-09-22T19:41:08Z",
    "status": "In Progress",
    "period": "Q3",
    "clock": "07:21",
    "live": true,
    "ended": false,
    "scores": [
      { "team": "Los Angeles Lakers", "score": "78" },
      { "team": "Boston Celtics", "score": "81" }
    ],
    "series_format": null,
    "snapshot_url": "https://0xinsider.com/event/nba-lal-bos-2026-09-22"
  }
}

​

Check the signature

signature = "v1=" + hex( HMAC_SHA256( signing_secret, timestamp + "." + raw_body ) )

• Calculate the HMAC from the raw request bytes. Parsing and re-serializing JSON can change those bytes.
• Use the whole whsec_... string as the key, prefix included.
• Reject a request whose x-0xinsider-timestamp is more than 300 seconds from your own clock.
• Split x-0xinsider-signature on commas and accept the request when any candidate matches. A staged rotation sends two candidates for an hour.
• Compare each candidate in constant time.
• Deduplicate ordinary events on x-0xinsider-event-id before acting. The verification challenge has no event ID; handle it separately.

import crypto from "node:crypto";

const SECRET = process.env.OXINSIDER_WEBHOOK_SECRET;
if (!SECRET) throw new Error("Set OXINSIDER_WEBHOOK_SECRET before starting the receiver");
const TOLERANCE_SECONDS = 300;

function verify(rawBody, signatureHeader, timestampHeader) {
  const ts = Number(timestampHeader);
  if (!Number.isFinite(ts)) return false;
  if (Math.abs(Date.now() / 1000 - ts) > TOLERANCE_SECONDS) return false;

  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", SECRET)
      .update(`${timestampHeader}.${rawBody}`)
      .digest("hex");

  // A staged rotation sends two comma-separated candidates. Accept either.
  return signatureHeader
    .split(",")
    .map((s) => s.trim())
    .some((candidate) => {
      const a = Buffer.from(candidate);
      const b = Buffer.from(expected);
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    });
}

import hashlib
import hmac
import os
import time

SECRET = os.environ["OXINSIDER_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 300

def verify(raw_body: bytes, signature_header: str, timestamp_header: str) -> bool:
    try:
        ts = int(timestamp_header)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False

    signed = f"{timestamp_header}.".encode() + raw_body
    expected = "v1=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()

    # A staged rotation sends two comma-separated candidates. Accept either.
    return any(
        hmac.compare_digest(part.strip(), expected)
        for part in signature_header.split(",")
    )

​

Handle retries and disabled webhooks

• failure_count on the endpoint counts consecutive failed attempts across all of its deliveries. Any success resets it to 0.
• At 8 consecutive failures the endpoint’s status becomes disabled and 0xinsider emails the account owner.
• Several failing deliveries can reach this limit before any one delivery uses all 8 attempts.

​

Replay after downtime

1. Store next_cursor from every replay response.
2. After the outage, call /api/v1/events/feed/since?cursor=<the cursor you stored>.
3. Process each event in data, then store the response’s new next_cursor.
4. Repeat while has_more is true.

​

Rotate the signing secret

​

Staged rotation, with a 1-hour overlap

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Idempotency-Key: webhook-prepare-2026-09-22" \
  "https://api.0xinsider.com/api/v1/webhooks/42/rotate-secret/prepare"

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Idempotency-Key: webhook-activate-2026-09-22" \
  "https://api.0xinsider.com/api/v1/webhooks/42/rotate-secret/activate"

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Idempotency-Key: webhook-retire-2026-09-22" \
  "https://api.0xinsider.com/api/v1/webhooks/42/rotate-secret/retire"

​

Immediate rotation, after a leak

curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Idempotency-Key: webhook-rotate-2026-09-22" \
  "https://api.0xinsider.com/api/v1/webhooks/42/rotate-secret"

​

Limits

• Deliver to a laptop or a private network. The URL has to be public HTTPS on port 443. To read events from a machine with no public address, open the Stream instead.
• The count event large_trades_inserted does not contain individual trades. Choose large_trade_inserted_v2 for one trade per delivery.
• Replay any event type other than large_trades_inserted (whale_trades_inserted).
• Count events cannot filter individual trades. For large_trade_inserted_v2, set trade_filters to filter by market, wallet, minimum grade, or minimum size.
• Return signing_secret a second time. Webhook and Webhooks never carry it, so rotate the secret if you lose it.