Skip to main content
POST
cURL
Use this route after creating a webhook or changing its URL. It returns 202 with a durable attempt and status_url; your endpoint stays pending until its receiver accepts a signed challenge. Use Get webhook verification to read the result, or Verify a webhook when you need the existing synchronous response.

​
Parameters

​
Key response fields

The same endpoint and token recover the same attempt even with a different idempotency key. An idempotency replay keeps the original response, so poll status_url for changes. A terminal attempt never starts again; change the URL to obtain a new token if you need a new verification.

​
The signed challenge

Your receiver validates the existing timestamp and HMAC signature, then answers with 2xx within 10 seconds. The asynchronous challenge also carries verification_attempt_id in its JSON body and x-0xinsider-verification-attempt in its headers. Use that stable UUID to correlate repeated requests; delivery can occur more than once after a timeout or worker restart. Transient DNS, connection, timeout, 429, and 5xx failures can retry up to 4 claimed challenges. An unsafe destination or another non-success status ends the attempt. Expiry, disabling the endpoint, changing its URL or verification identity, or losing the owner’s access prevents activation.

​
Example

SDK 0.17.0 provides both methods. API keys and OAuth tokens with webhooks scope keep the existing webhook access and quota rules.

​
What it does not do

  • Return the verification token, signing secret, receiver response body, resolved address, or internal error text in status.
  • Activate your endpoint on admission alone.
  • Refresh a token or restart a terminal attempt.
  • Make your receiver part of the admission response time. The challenge runs after the durable admission commits.

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

Path Parameters

​
id
integer<int64>
required

Webhook endpoint id owned by the authenticated API key user.

Body

application/json

Original verification token; never use the signing secret here.

​
verification_token
string
required

The original one-time token returned by webhook creation or a URL change. Sent only in the request body and signed receiver challenge.

Required string length: 1 - 255

Response

Durable admission; poll status_url for activation or terminal outcome.

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