lookback_s seconds would this configuration have delivered? The configuration is validated and normalised exactly as a create, then evaluated against recent history. Nothing is stored and no delivery is sent. Available for account.fill, account.transfer and market.liquidation; another type is refused with the list of the ones that work. An address scoped type needs at least one watched wallet to report on. Authenticate with an API key or a signed-in dashboard session. Available on every plan, including Free, and metered like the market data it returns. At most six estimates and dry-runs a minute per account, shared between the two.
Route Metadata
| Field | Value |
|---|---|
| Method | POST |
| Path | /v1/webhooks/subscriptions/dry-run |
| operationId | dryRunWebhookSubscription |
| Tag | Webhooks - Previews |
| Family | Webhooks |
| Deprecated or legacy | no |
Request Body
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription request body",
"description": "A would-be subscription to evaluate against recent history. Same shape as a create, without the endpoint, plus the window.",
"type": "object",
"required": [
"event_type"
],
"properties": {
"config": {
"description": "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.",
"type": "object",
"properties": {
"addresses": {
"description": "Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]
},
"conditions": {
"description": "Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.",
"type": "array",
"items": {
"description": "One condition on an event metric. The operator vocabulary is grouped by the metric's type; see `operators` on the event type.",
"type": "object",
"required": [
"metric",
"op"
],
"properties": {
"metric": {
"description": "A metric declared by the event type.",
"type": "string",
"example": "notional_usd"
},
"op": {
"description": "Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.",
"type": "string",
"enum": [
"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"
},
"value": {
"description": "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
}
}
}
},
"min_notional_usd": {
"description": "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.",
"type": "number",
"example": 100000
},
"params": {
"description": "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.",
"type": "object",
"additionalProperties": true,
"example": {
"max_age_s": 3600
}
},
"symbols": {
"description": "Instrument symbols to match. Omit to match every symbol.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"BTC",
"ETH"
]
},
"venue": {
"description": "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.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"example": "hyperliquid"
}
}
},
"event_type": {
"description": "Event type to evaluate.",
"type": "string",
"example": "market.liquidation"
},
"limit": {
"description": "Occurrences to return, newest first.",
"type": "integer",
"format": "int64",
"default": 100,
"minimum": 1,
"maximum": 200,
"example": 100
},
"lookback_s": {
"description": "Seconds of history to scan, ending now.",
"type": "integer",
"format": "int64",
"default": 3600,
"minimum": 60,
"maximum": 86400,
"example": 3600
}
}
}
Response Contracts
Status 200
Occurrences the configuration would have deliveredapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 200",
"description": "API response containing a subscription dry-run.",
"type": "object",
"properties": {
"data": {
"description": "Which occurrences in the requested window a would-be subscription would have delivered. Nothing is stored and no delivery is sent.",
"type": "object",
"required": [
"event_type",
"matched",
"occurrences",
"truncated",
"window"
],
"properties": {
"event_type": {
"description": "Event type that was evaluated.",
"type": "string",
"example": "market.liquidation"
},
"matched": {
"description": "Occurrences that matched inside the window, before `limit` is applied.",
"type": "integer",
"example": 37
},
"occurrences": {
"description": "Newest first, at most `limit`.",
"type": "array",
"items": {
"description": "One occurrence that would have been delivered, in the shape the delivered payload carries.",
"type": "object",
"required": [
"data",
"observed_at_estimate"
],
"properties": {
"data": {
"description": "The occurrence body, the same `data` a delivery would carry.",
"type": "object",
"additionalProperties": true
},
"observed_at_estimate": {
"description": "The occurrence's own timestamp. A real delivery's `observed_at` is this plus the time it takes to see the occurrence.",
"type": "string",
"format": "date-time"
}
}
}
},
"truncated": {
"description": "True when fewer occurrences are returned than matched, or when a scan hit its row cap and the window was narrowed.",
"type": "boolean",
"example": false
},
"window": {
"description": "The window a preview vouches for. It can start later than the one that was asked for when a scan reached its row cap.",
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"from": {
"description": "Start of the window the answer covers.",
"type": "string",
"format": "date-time"
},
"to": {
"description": "End of the window, which is the moment of the request.",
"type": "string",
"format": "date-time"
}
}
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
Status 400
Invalid requestapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 400",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"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"
}
Status 401
Authentication requiredapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 401",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 401,
"error": "Missing or invalid API key. Provide X-API-Key header."
}
Status 429
Rate limit exceededapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 429",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 429,
"error": "Rate limit exceeded"
}
Status 503
The dry-run could not be produced right now. Retry shortly.application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 503",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"code": 503,
"error": "dry-run is temporarily unavailable",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status 504
The scan ran out of time before it could answer. Narrow the window or the configuration and try again.application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "dryRunWebhookSubscription response 504",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
}
OpenAPI example
{
"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"
}