---
title: "Dry-run a webhook subscription"
method: POST
path: "/v1/webhooks/subscriptions/dry-run"
tags: ["Webhooks - Previews"]
---

# Dry-run a webhook subscription

`POST /v1/webhooks/subscriptions/dry-run`

## Request

- Base URL: `https://api.0xarchive.io`
- URL: `https://api.0xarchive.io/v1/webhooks/subscriptions/dry-run`
- Auth: API key in header `X-API-Key`

Which occurrences in the last `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.

## Request body

- WebhookDryRunRequest: 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.
  - `config` WebhookSubscriptionConfig: 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.
    - `venue` union: 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.
      - string
      - string[]
    - `symbols` string[]: Instrument symbols to match. Omit to match every symbol.
    - `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.
    - `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.
    - `conditions` WebhookSubscriptionCondition[]: Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.
      - `metric` string, required: A metric declared by the event type.
      - `op` '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', required: Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.
      - `value` unknown
    - `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.
  - `filters` WebhookSubscriptionConfig: 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.
    - `venue` union: 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.
      - string
      - string[]
    - `symbols` string[]: Instrument symbols to match. Omit to match every symbol.
    - `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.
    - `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.
    - `conditions` WebhookSubscriptionCondition[]: Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.
      - `metric` string, required: A metric declared by the event type.
      - `op` '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', required: Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.
      - `value` unknown
    - `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.
  - `lookback_s` integer: Seconds of history to scan, ending now. Between 60 and 86400 (24 hours); a value outside that range is refused with a 400.
  - `limit` integer: Occurrences to return, newest first. Between 1 and 200; a value outside that range is refused with a 400.

## Response `200`

Occurrences the configuration would have delivered

- ApiResponseWebhookDryRun: API response containing a subscription dry-run.
  - `success` boolean
  - `data` WebhookDryRun: Which occurrences in the requested window a would-be subscription would have delivered. Nothing is stored and no delivery is sent.
    - `event_type` string, required: Event type that was evaluated.
    - `window` WebhookPreviewWindow, 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.
      - `from` string, date-time, required: Start of the window the answer covers.
      - `to` string, date-time, required: End of the window, which is the moment of the request.
    - `matched` integer, required: Occurrences that matched inside the window, before `limit` is applied.
    - `truncated` boolean, required: True when fewer occurrences are returned than matched, or when a scan hit its row cap and the window was narrowed.
    - `occurrences` WebhookPreviewOccurrence[], required: Newest first, at most `limit`.
      - `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` object, required: The occurrence body, the same `data` a delivery would carry.
    - `notes` string[]: Advisories about the scan, for example a venue that could not be read. Omitted when there are none.

## Other responses

- `400`: Invalid request: a parameter, symbol, interval, cursor or time range failed validation. See `error_code`.
- `401`: Authentication required: the API key is missing or invalid.
- `429`: Rate limit, concurrency limit or monthly credits exceeded. See `error_code`.
- `503`: The dry-run could not be produced right now. Retry shortly.
- `504`: The scan ran out of time before it could answer. Narrow the window or the configuration and try again.
- `default`: Any other error. The body is an `ErrorResponse`; branch on `error_code`. A 503 (`upstream_unavailable`) carries `Retry-After`.

---

[API](https://skmtc.dev/0xarchive/apis/0xarchive-api-2.md) · [All operations](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/revisions/27076f55595f?raw)