---
title: "Estimate a webhook subscription"
method: POST
path: "/v1/webhooks/subscriptions/estimate"
tags: ["Webhooks - Previews"]
---

# Estimate a webhook subscription

`POST /v1/webhooks/subscriptions/estimate`

## Request

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

How often would this configuration have fired over the last `lookback_days`? Returns the total, a count per day of the window, the median and busiest day, the distribution of the event's primary metric, a ladder of what the daily rate would be at other thresholds, and a sample of real matches, so a threshold can be chosen against history rather than guessed. The configuration is validated and normalised exactly as a create. Nothing is stored and no delivery is sent. Available for `account.fill`, `account.transfer`, `account.liquidated`, `market.liquidation`, `market.pga_payment`, `hip4.settlement`, `market.liquidation_burst`, `market.oi_delta`, `oracle.jump` and `market.funding_flip`; 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

- WebhookEstimateRequest: A would-be subscription to evaluate against 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_days` integer: Days of history to evaluate, ending now. Between 1 and 30; a value outside that range is refused with a 400. Some event types evaluate a shorter window (for example 7 days for `account.fill`); the response's `days` and `basis.note` then say so.

## Response `200`

How often the configuration would have fired

- ApiResponseWebhookEstimate: API response containing a subscription estimate.
  - `success` boolean
  - `data` WebhookEstimate: How often a would-be subscription would have fired over the requested window. 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.
    - `days` integer, required: Days the answer covers. Shorter than requested when the event type carries a shorter cap.
    - `total` integer, required: Occurrences that would have been delivered across the window.
    - `per_day` WebhookEstimateDayCount[], required: One entry per day, oldest first, zero filled. The last entry ends at the moment of the request.
      - `date` string, date, required: UTC date the bin ends on.
      - `count` integer, required: Occurrences that would have been delivered in the bin.
    - `per_day_p50` number, required: Median deliveries a day across the window.
    - `per_day_max` integer, required: Busiest day in the window.
    - `primary_metric` string, nullable: The metric the ladder and the distribution are about. Null when the type has none.
    - `ladder` WebhookEstimateRung[], required: Ascending. Empty when there is no primary metric.
      - `value` number, required: Threshold on the primary metric.
      - `per_day` number, required: Deliveries a day at that threshold, everything else unchanged.
    - `distribution` WebhookEstimateDistribution: Quantiles of the primary metric over the matched occurrences, for choosing a threshold against real history.
      - `n` integer, required: Occurrences the quantiles are computed over.
      - `p50` number, required: Median.
      - `p90` number, required: 90th percentile.
      - `p99` number, required: 99th percentile.
      - `max` number, required: Largest value seen.
    - `sample` WebhookPreviewOccurrence[], required: Newest matches first, in the same shape the dry-run returns.
      - `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.
    - `basis` WebhookEstimateBasis, required: How the estimate was produced, so the numbers can be read for what they are.
      - `mode` 'exact' | 'sampled' | 'replayed', required: `exact` counted every occurrence in the window. `sampled` scaled the counts from a capped scan, and the note says by how much. `replayed` re-ran a windowed rule over history at your own parameters.
      - `note` string, nullable: What qualifies the numbers, when anything does.

## 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 estimate could not be produced right now. Retry shortly.
- `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)