Webhooks

A webhook is a signed HTTPS POST that 0xinsider sends to your server every time an event you subscribed to fires. This page gets you a verified endpoint, a signature check that runs before you parse the body, and a way to catch up after downtime. Every webhook route needs an API key on an active Pro subscription. Without one the API answers 402 with error.reason subscription_inactive.

Choose event types

Webhook events returns this catalog. Put the types you want in event_types when you create the endpoint.

Event type	Pro only	Status	`data` fields
`large_trades_inserted`	Yes	`active`	`count`
`whale_trades_inserted`	Yes	`active`	The same event and the same fields as `large_trades_inserted`, under its older spelling
`large_trade_inserted_v2`	Yes	`active`	One trade: market, wallet, grade snapshot, size, shares, price, side, outcome, and trade time
`wallet_grade_changed`	Yes	`active`	`wallet`, `trader_id`, `old_grade`, `new_grade`, `direction`, `skill_index`, `final_score`, `date`
`suspicious_trade_flagged`	Yes	`active`	`trade_id`, `wallet`, `trader_id`, `condition_id`, `suspicion_score`, `track`, `side`, `size`, `price`
`insider_radar_flag_raised`	Yes	`active`	The same event and the same fields as `suspicious_trade_flagged`, under its older spelling
`smart_money_flow_detected`	Yes	`active`	`condition_id`, `net_flow_usd`, `abs_net_flow_usd`, `dominant_side`, `grade_floor`, `whale_trade_count`, `window`
`trader_synced`	No	`active`	`trader_id`, `wallet`
`whale_trader_synced`	No	`active`	The same event and the same fields as `trader_synced`, under its older spelling
`large_positions_updated`	No	`active`	`count`
`live_sports_updated`	No	`active`	`event_slug`, `game_id`, `league`, `version`, `changed`, `observed_at`, `published_at`, `status`, `period`, `clock`, `live`, `ended`, `scores`, `series_format`, `snapshot_url`
`export_job_ready`	Owner only	`active`	`job_id`, `status` (`ready`), `format`, `next_action` (`download`), `total_trades`, `processed_trades`, `file_size`, `data_as_of`
`export_job_failed`	Owner only	`active`	`job_id`, `status` (`failed`), `format`, `next_action` (`resubmit`), `failure_reason`
`export_job_expired`	Owner only	`active`	`job_id`, `status` (`expired`), `format`, `next_action` (`resubmit`)
`export_job_cancelled`	Owner only	`active`	`job_id`, `status` (`cancelled`), `format`, `next_action` (`resubmit`)

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.
The four export_job_* events go only to endpoints owned by the account that submitted the export.
When a Pro subscription lapses, every queued delivery of a Pro-only type moves to dead_letter with last_error set to delivery owner is no longer authorized for this event.

Create and verify the endpoint

Create it

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"

The response shows signing_secret (whsec_...) and verification.token (whv_...) once each. Store both now, because no later read returns either one. The endpoint receives nothing until step 2.

Verify it within 24 hours

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"

The call sends a signed webhook.verification challenge to your URL. Your server has to answer 2xx within 10 seconds before the endpoint becomes active. Holding the token is not enough on its own.

The challenge body is {"type":"webhook.verification","token":"<verification_token>","webhook_id":<id>}. It is signed the same way a delivery is, and it carries x-0xinsider-timestamp, x-0xinsider-signature, and x-0xinsider-event-type webhook.verification. It carries none of the event, delivery, or idempotency headers listed below. Two answers mean the endpoint did not activate:

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.

What a delivery carries

A delivery is a POST with a JSON body and the User-Agent 0xinsider-webhooks/1.0. Answer with any 2xx within 15 seconds, then do your processing after you have replied.

Header	Value
`x-0xinsider-signature`	The HMAC-SHA256 signature, as `v1=<hex>`. During a staged secret rotation it holds two comma-separated candidates.
`x-0xinsider-timestamp`	The Unix time in seconds at which 0xinsider signed the body.
`x-0xinsider-event-id`	The event’s id. It is the same on every retry of that event.
`x-0xinsider-event-type`	The event type, one of the types in the catalog above.
`x-0xinsider-delivery-id`	The `id` of this delivery’s row in the delivery log.
`x-0xinsider-delivery-attempt`	Which attempt this is, counting from 1.
`idempotency-key`	A stable key for this endpoint and event pair. It does not change between retries.

{
  "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

live_sports_updated sends one pulse per game. A pulse goes out when a material field moves since that game’s last pulse: scores, status, period, live, or ended. The game clock moving on its own never sends one, and the clock still rides every pulse. Two rules bound the volume. An ordinary change waits out 20 seconds since that game’s last pulse: the pulse goes out on the first frame the provider sends after that. A game going live or final ignores the wait, and so does a game’s first pulse, so you never miss a start or a final. A game that stops sending frames stops sending pulses. Live games send a frame about every 20 seconds, and the frame that ends a game is exempt from the wait, so a finished game always sends its last pulse. A change that arrives inside the 20 seconds is not dropped. The next pulse lists it in changed and its body carries the current state, so you see every field that moved, but not every value it passed through.

Field	What it is
`event_slug`	The Polymarket event slug the game trades under.
`game_id`	The provider’s game id, as a string. `null` when the frame carried none.
`league`	The league abbreviation, such as `NBA`. `null` when the frame carried none.
`version`	A counter for this game that goes up by one per pulse. Deliveries are not ordered, so drop a pulse whose `version` you already have.
`changed`	The material fields that moved since this game’s previous pulse.
`observed_at`	When the provider stamped the frame this pulse reports. `null` when the frame carried no time.
`published_at`	When 0xinsider sent the pulse.
`status`, `period`, `clock`	The provider’s status text, period text, and game clock. Each is `null` when the frame carried none.
`live`, `ended`	Whether the game is in play and whether the provider has called it final.
`scores`	One entry per side: `team`, `score`, and `map_score` on esports series.
`series_format`	The `BoN` token on an esports series. `null` on every other sport.
`snapshot_url`	The game’s page on 0xinsider. Read it after a gap instead of replaying 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

The signature covers the timestamp and the raw body, joined by a dot.

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

Sign the raw request bytes. Parsing the JSON and serializing it again changes the HMAC.
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 on x-0xinsider-event-id before you act on the event.

import express from "express";
import crypto from "node:crypto";

const SECRET = process.env.OXINSIDER_WEBHOOK_SECRET;
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);
    });
}

const app = express();

// Capture the raw body. Do NOT run a JSON parser before verifying.
app.post(
  "/webhooks/0xinsider",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const ok = verify(
      rawBody,
      req.get("x-0xinsider-signature") ?? "",
      req.get("x-0xinsider-timestamp") ?? ""
    );
    if (!ok) return res.status(400).send("bad signature");

    const event = JSON.parse(rawBody);
    // Deduplicate on event.id, then reply before you process the event.
    res.status(200).send("ok");
    handleEvent(event).catch(console.error);
  }
);

import hashlib
import hmac
import os
import time
from flask import Flask, request

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(",")
    )

app = Flask(__name__)

@app.post("/webhooks/0xinsider")
def receive():
    raw_body = request.get_data()  # raw bytes, before any JSON parse
    ok = verify(
        raw_body,
        request.headers.get("x-0xinsider-signature", ""),
        request.headers.get("x-0xinsider-timestamp", ""),
    )
    if not ok:
        return "bad signature", 400

    event = request.get_json()
    # Deduplicate on event["id"], then return 200 before you process the event.
    return "ok", 200

Retries

An attempt fails when your server answers outside 2xx, the connection errors, or the request runs past the 15-second deadline. A delivery gets 8 attempts in total. After the eighth failure its status becomes dead_letter and 0xinsider stops. Each failed attempt doubles the ceiling on the next wait: 60 seconds after the first failure, then 120, 240, 480, 960, 1,920, and 3,600 seconds. The delivery worker wakes every 10 seconds, so a wait can run up to 10 seconds longer than its ceiling. The wait you get inside that ceiling depends on how the attempt failed. Each row below names the value the delivery log reports in retry_schedule_reason.

How the attempt failed	The wait	`retry_schedule_reason`
Your server answered `408`, `429`, or `5xx` and sent a usable `Retry-After`.	The header’s value, clamped to between 60 and 3,600 seconds.	`receiver_retry_after`
Your server answered `408`, `429`, or `5xx` without a usable `Retry-After`, or the connection failed or timed out.	A random value between half the ceiling and the ceiling. Two endpoints that fail at the same moment do not retry at the same moment.	`transient_failure`
Your server answered with any other status outside `2xx`.	The full ceiling.	`permanent_or_auth_failure`

Retry-After is read as a number of seconds or as an HTTP-date. A missing, malformed, or already-past value is ignored, and the delivery falls back to its ordinary wait. Webhook deliveries reports status, last_error, next_attempt_at, and retry_schedule_reason on each row, and keeps rows for 7 days. Two more reasons appear there: manual_redelivery after Redeliver a webhook delivery, and configuration_changed when an edit to the endpoint released an attempt that had not been sent. Both next_attempt_at and retry_schedule_reason are null while an attempt is in flight and once the delivery is delivered or dead_letter. One delivery can therefore keep retrying for up to 7,380 seconds, a little over 2 hours. The endpoint itself is usually disabled long before that:

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.
A busy endpoint that goes down is therefore disabled within minutes, not hours.

Disabling an endpoint moves every queued delivery to dead_letter. Re-enabling it with {"enabled": true} on Update a webhook does not resend them. Requeue each one with Redeliver a webhook delivery, or catch up with the replay below.

Replay after downtime

Event replay is the only durable catch-up, and it covers large_trades_inserted (whale_trades_inserted) alone. Every other type is delivered, retried, and then dropped.

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

Rotate the signing secret

Rotate the secret when it reaches git, a log, a screenshot, or anyone who should not have it. There are two ways to do it.

Staged rotation, with a 1-hour overlap

Use this one unless you are racing a leak. Both secrets verify while you deploy the new one, so no delivery is rejected on the way.

Prepare the new secret

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"

Prepare a staged webhook secret returns the new signing_secret and sets secret_rotation.status to pending. Deliveries keep using the current secret. Deploy the new one to every receiver before you move on.

Activate it

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"

Activate a staged webhook secret promotes the prepared secret and returns it once more. secret_rotation.status becomes overlap, and secret_rotation.overlap_expires_at is the instant the overlap ends, 1 hour later. Until then x-0xinsider-signature carries two comma-separated v1=<hex> candidates: the new secret’s signature first, the old secret’s second.

Retire the old secret

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"

Retire a staged webhook secret ends the overlap as soon as every receiver accepts the new secret. secret_rotation.status goes back to idle and deliveries carry one signature again. If you never call it, the overlap ends on its own at overlap_expires_at.

All three calls take an Idempotency-Key. Repeating prepare with the same key while a secret is still pending returns that same secret, so a lost response costs you nothing. Changing the endpoint’s url on Update a webhook discards a prepared or overlapping secret.

Immediate rotation, after a leak

Rotate a webhook secret replaces the secret in a single call.

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"

The old secret stops working when the call returns, and there is no overlap. Deploy the new signing_secret to every receiver immediately: a delivery your server rejects is retried about a minute later and counts toward the 8 consecutive failures that disable the endpoint. A 409 with error.reason webhook_delivery_in_progress means a delivery is in flight, so send the request again once it finishes.

What it does not do

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.
Carry the trades themselves. large_trades_inserted says how many new large trades there are, not which ones.
Replay any event type other than large_trades_inserted (whale_trades_inserted).
Filter by market, size, or grade. Subscribe to the type and filter in your own code; Alert bot shows that loop.
Return signing_secret a second time. Webhook and Webhooks never carry it, so rotate the secret if you lose it.

Getting started

Integrations

Guides

Concepts

Choose event types

Create and verify the endpoint

What a delivery carries

Live game pulses

Check the signature

Retries

Replay after downtime

Rotate the signing secret

Staged rotation, with a 1-hour overlap

Immediate rotation, after a leak

What it does not do

​Choose event types

​Create and verify the endpoint

​What a delivery carries

​Live game pulses

​Check the signature

​Retries

​Replay after downtime

​Rotate the signing secret

​Staged rotation, with a 1-hour overlap

​Immediate rotation, after a leak

​What it does not do

Choose event types

Create and verify the endpoint

What a delivery carries

Live game pulses

Check the signature

Retries

Replay after downtime

Rotate the signing secret

Staged rotation, with a 1-hour overlap

Immediate rotation, after a leak

What it does not do