Skip to main content
POST
cURL
The new endpoint starts at status pending_verification and receives nothing until Verify a webhook activates it. Pick the event types first from Webhook events, or from Choose event types in the guide.

​
Parameters

One account holds at most 10 endpoints. An 11th create answers 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 answers 400.

​
Key response fields

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

​
Example

​
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).

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
​
trade_filters
object

All present fields narrow large_trade_inserted_v2 delivery. Grade is observed at publication; ungraded trades do not match min_grade. An empty object matches every large trade.

Response

Webhook destination

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