Dry-run a webhook subscription

curl --request POST \
  --url https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_type": "market.liquidation"
}
'

import requests

url = "https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run"

payload = { "event_type": "market.liquidation" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({event_type: 'market.liquidation'})
};

fetch('https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run"

	payload := strings.NewReader("{\n  \"event_type\": \"market.liquidation\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "event_type": "market.liquidation",
    "window": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "matched": 37,
    "truncated": false,
    "occurrences": [
      {
        "observed_at_estimate": "2023-11-07T05:31:56Z",
        "data": {}
      }
    ]
  }
}

{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}

{
  "code": 429,
  "error": "Rate limit exceeded"
}

{
  "code": 503,
  "error": "dry-run is temporarily unavailable",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

{
  "code": 504,
  "error": "dry-run timed out before it could scan the whole window; try a shorter lookback_s",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

POST

https://api.0xarchive.io

webhooks

subscriptions

dry-run

Dry-run a webhook subscription

curl --request POST \
  --url https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_type": "market.liquidation"
}
'

import requests

url = "https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run"

payload = { "event_type": "market.liquidation" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({event_type: 'market.liquidation'})
};

fetch('https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run"

	payload := strings.NewReader("{\n  \"event_type\": \"market.liquidation\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "event_type": "market.liquidation",
    "window": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "matched": 37,
    "truncated": false,
    "occurrences": [
      {
        "observed_at_estimate": "2023-11-07T05:31:56Z",
        "data": {}
      }
    ]
  }
}

{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}

{
  "code": 429,
  "error": "Rate limit exceeded"
}

{
  "code": 503,
  "error": "dry-run is temporarily unavailable",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

{
  "code": 504,
  "error": "dry-run timed out before it could scan the whole window; try a shorter lookback_s",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}

API key required. Send X-API-Key with this request. See REST authentication.

Shared request rules

Machine schema

Open the generated operation schema for machine-readable request and response details.

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at https://0xarchive.io/dashboard

Body

application/json

A would-be subscription to evaluate against recent history. Same shape as a create, without the endpoint, plus the window.

event_type

string

required

Event type to evaluate.

Example:

"market.liquidation"

config

object

What a subscription matches on. Every key is checked against the event type's catalog declaration, so an unknown key, an undeclared parameter or a condition on an undeclared metric is refused rather than ignored. The stored config is the normalised form: venues and addresses lowercased, declared parameters filled in at their defaults, and operators written in their canonical spelling.

Hide child attributes

config.venue

Venue or venues to match, from the event type's venues list. Accepts a single string, a pipe separated string or a list. Omit to match every covered venue.

Example:

"hyperliquid"

config.symbols

string[]

Instrument symbols to match. Omit to match every symbol.

Example:

["BTC", "ETH"]

config.addresses

string[]

Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.

Example:

[
  "0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]

config.params

object

Parameter values for the event type, keyed by the parameter names it declares. A declared parameter you leave out is stored at its default. A declared parameter may also be written at the top level of the config.

Example:

{ "max_age_s": 3600 }

config.conditions

object[]

Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.

Hide child attributes

config.conditions.metric

string

required

A metric declared by the event type.

Example:

"notional_usd"

config.conditions.op

enum<string>

required

Comparison to apply. Symbol spellings such as >= are accepted on the way in and stored in the canonical spelling shown here.

Available options:

greater_than,

greater_than_or_equal,

less_than,

less_than_or_equal,

equal,

not_equal,

between,

not_between,

in,

not_in,

contains,

not_contains,

starts_with,

ends_with,

before,

after,

is_empty,

is_not_empty

Example:

"greater_than_or_equal"

config.conditions.value

any

What to compare against. A number, string, boolean or RFC 3339 timestamp for a single value comparison; a two entry [low, high] list for between and not_between; a non-empty list for in and not_in. Omitted for is_empty and is_not_empty.

Example:

100000

config.min_notional_usd

number

Shorthand for a notional_usd at-or-above condition, kept for compatibility. It is stored as a condition, and it is mirrored back here as the loosest notional lower bound the config carries.

Example:

100000

lookback_s

integer<int64>

default:3600

Seconds of history to scan, ending now.

Required range: 60 <= x <= 86400

Example:

3600

limit

integer<int64>

default:100

Occurrences to return, newest first.

Required range: 1 <= x <= 200

Example:

100

Response

Occurrences the configuration would have delivered

API response containing a subscription dry-run.

success

boolean

Example:

true

data

object

Which occurrences in the requested window a would-be subscription would have delivered. Nothing is stored and no delivery is sent.

Hide child attributes

data.event_type

string

required

Event type that was evaluated.

Example:

"market.liquidation"

data.window

object

required

The window a preview vouches for. It can start later than the one that was asked for when a scan reached its row cap.

Hide child attributes

data.window.from

string<date-time>

required

Start of the window the answer covers.

data.window.to

string<date-time>

required

End of the window, which is the moment of the request.

data.matched

integer

required

Occurrences that matched inside the window, before limit is applied.

Example:

37

data.truncated

boolean

required

True when fewer occurrences are returned than matched, or when a scan hit its row cap and the window was narrowed.

Example:

false

data.occurrences

object[]

required

Newest first, at most limit.

Hide child attributes

data.occurrences.observed_at_estimate

string<date-time>

required

The occurrence's own timestamp. A real delivery's observed_at is this plus the time it takes to see the occurrence.

data.occurrences.data

object

required

The occurrence body, the same data a delivery would carry.

Last modified on September 20, 2026

API reference

SDKs & tooling

AI & agents

Dry-run a webhook subscription

Authorizations

Body

Response