Skip to main content
PATCH
cURL
Use this endpoint to update a receiver’s URL, choose different events, or pause deliveries. Fields you omit keep their existing values. A supplied trade_filters object replaces the previous filters. A changed URL needs verification before deliveries resume. To remove the endpoint, use Delete a webhook.

Parameters

A URL that differs only in host case, a trailing dot after the host, or an explicit :443 is not a change, so it does not reset verification. Every successful PATCH sets failure_count back to 0. A URL change that does take effect also cancels a staged secret rotation. Any prepared secret is dropped, and any overlap ends at once, so the endpoint returns to secret_rotation.status idle.
enabled: false moves every delivery still queued for this endpoint to dead_letter, and enabled: true resends none of them. Requeue each one with Redeliver a webhook delivery, or catch up from Event replay.

Example

To filter on the grade the wallet held when the trade filled, send the new filters whole. They replace the old ones, so a min_grade you set before is dropped:

Handle a 409 or a 422

What it does not do

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

Path Parameters

id
integer<int64>
required

Webhook endpoint id owned by the authenticated API key user.

Body

application/json

Webhook fields to replace or preserve.

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

Replacement public HTTPS callback URL on the default port 443, validated and checked for uniqueness exactly like the create url. HTTPS scheme/host case, trailing DNS dots and port 443 normalize; path/query case is preserved. Changing it resets status to pending_verification and returns a new verification token; the new destination must pass the verification challenge before deliveries resume.

event_types
enum<string>[]
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.

enabled
boolean

Response

Webhook destination

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