Skip to main content
POST
cURL
Create an endpoint that sends events to your HTTPS receiver. Choose its event_types from Webhook events. The endpoint starts as pending_verification. Store the returned signing secret and verification token, then call Verify a webhook before it can receive events.

Parameters

An account holds at most 10 endpoints on Pro, or 40 on Max. A create over that limit returns 400, and deleting an endpoint frees its slot. Two endpoints on your account cannot hold the same URL. Host case, a trailing dot after the host, and an explicit :443 do not make a URL different, but the path and the query are compared exactly as you sent them. A duplicate returns 400.

Key response fields

The response shows two values, once each. Store both before you do anything else.

Trade filters

trade_filters narrows large_trade_inserted_v2 deliveries. A delivery goes out only when the trade matches every field you send. Send min_grade or min_grade_at_trade, not both. Both together return 400 with error.param set to trade_filters.min_grade_at_trade.

Example

This endpoint receives each large trade of $25,000 or more by a wallet that held an S or A grade when the trade filled:

Retry with the same key

A timeout can leave you unsure whether the endpoint was created. Send the request again with the same Idempotency-Key and the same body, and you get the first response back, including the same signing_secret.

What it does not do

  • Deliver anything yet. Your server has to answer the signed webhook.verification challenge with a 2xx first, and Verify a webhook is what sends it.
  • Accept an http:// URL, a port other than 443, a URL carrying credentials, or a host that is not publicly routable.
  • Show signing_secret or verification.token a second time. Both appear once, in this response.
  • Recover a lost signing secret. Replace it instead: Rotate a webhook secret swaps it at once, and Prepare a staged webhook secret followed by Activate a staged webhook secret hands over with a 1-hour overlap.
  • Recover a lost verification token. Send a different url to Update a webhook for a fresh token, or delete the endpoint and create it again.

Authorizations

Authorization
string
header
required

Legacy default or named integration API key, or OAuth 2.1 access token, in the Authorization header as Bearer oxi_sk_live_... or Bearer oxi_at_.... Default keys retain full access; integration keys are limited to their approved read, webhooks, export and usage scopes and expire within 90 days. All credentials share the owner's account limits. Data calls require an active Pro subscription and return live data. A 401 carries WWW-Authenticate: Bearer resource_metadata="https://api.0xinsider.com/.well-known/oauth-protected-resource" (RFC 6750 section 3, RFC 9728).

Scopes

webhooks

Create, list, verify, rotate and delete webhook endpoints

Headers

X-Query-Validation
enum<string>

Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.

Available options:
strict
Idempotency-Key
string

Optional safe-retry key. Reuse the same value only when retrying the exact same mutation request body; a different body returns 422 and an in-flight matching request returns 409.

Required string length: 1 - 255

Body

application/json

Webhook destination to create.

name
string
required
Maximum string length: 100
url
string<uri>
required

Public HTTPS callback URL on the default port 443. Local, private, and internal targets are rejected, as is any explicit port other than 443 and any URL carrying credentials. Each user's URLs are unique after normalizing HTTPS scheme/host case, trailing DNS dots and port 443; path/query case is preserved. Pending verification and PATCH-disabled endpoints still reserve their stored URL. The destination must answer the signed webhook.verification challenge with a 2xx before POST /api/v1/webhooks/{id}/verify can activate the endpoint.

event_types
enum<string>[]
required
Minimum array length: 1
Available options:
large_trade_inserted_v2,
large_trades_inserted,
whale_trades_inserted,
live_sports_updated,
trader_synced,
whale_trader_synced,
large_positions_updated,
wallet_grade_changed,
suspicious_trade_flagged,
insider_radar_flag_raised,
sharp_money_flow_detected,
smart_money_flow_detected,
export_job_ready,
export_job_failed,
export_job_expired,
export_job_cancelled,
market_price_moved,
market_settled
trade_filters
object

All present fields narrow large_trade_inserted_v2 delivery. min_grade reads the payload's grade, observed at publication; min_grade_at_trade reads its grade_at_trade, the grade when the trade filled. Send one of the two, not both (400). An empty object matches every large trade.

price_move_filters
object

Settings for market_price_moved: required when event_types includes it, refused (400) when it does not. A PATCH without it keeps the stored settings; removing the event clears them. A subscription receives at most one delivery per market per window: the one level step whose (previous_level_cents, level_cents] holds min_move_cents.

settlement_filters
object

Settings for market_settled; every set field must match. Optional: subscribing without it stores {"sports_market_types": ["moneyline"]}, every market Polymarket labels moneyline, and sending it without the event is refused (400). That label is each head-to-head game's winner market, but in golf and other field events Polymarket labels every player market moneyline (winner, make the cut, round leader), so one tournament can send hundreds of states. Narrow it with leagues, which no market outside the list matches, including one whose league is null (a golf event slug that starts with a year, such as 2026-world-wide-technology-championship), or with condition_ids. A PATCH without it keeps the stored settings while the event stays subscribed; removing the event clears them. Stored as the API normalized it: trimmed and deduplicated, leagues, market types and condition IDs lowercased, and sports_market_types filled in when omitted.

Response

Webhook destination

object
string
required
Allowed value: "webhook"
data
object
required
meta
object
required