---
title: "Create a webhook subscription"
method: POST
path: "/v1/webhooks/subscriptions"
tags: ["Webhooks - Subscriptions"]
---

# Create a webhook subscription

`POST /v1/webhooks/subscriptions`

## Request

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

Subscribe an endpoint to an event type. The configuration is checked against the event type's catalog declaration before anything is stored, so an unknown key, an undeclared parameter, an out of range value or a condition on a metric the event does not carry is refused rather than quietly dropped. The endpoint must be one of yours. Addresses used in the configuration must already be on your watched list. A plan without webhook delivery, or one already at its subscription cap, is refused with the reason and the way forward. Authenticate with an API key or a signed-in dashboard session. Costs no credits.

## Request body

- WebhookSubscriptionCreateRequest: A new rule. The configuration is validated against the event type's catalog declaration before anything is stored. Send the configuration as `filters` or under its alias `config` (not both). Any other top-level key is refused with a 400 that names it.
  - `endpoint_id` string, uuid, required: Endpoint that will receive this rule's deliveries.
  - `event_type` string, required: Event type to subscribe to, from the catalog.
  - `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.
  - `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.

## Response `200`

The new subscription

- ApiResponseWebhookSubscription: API response containing one webhook subscription.
  - `success` boolean
  - `data` WebhookSubscription: A rule: one event type, one configuration, delivered to one endpoint.
    - `id` string, uuid, required: Subscription identifier.
    - `endpoint_id` string, uuid, required: Endpoint that receives this rule's deliveries.
    - `event_type` string, required: Event type this rule subscribes to.
    - `filters` WebhookSubscriptionConfig, required: 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.
    - `enabled` boolean, required: Your own on and off switch. Resuming a paused rule never changes it.
    - `created_at` string, date-time, required: When the rule was created.
    - `status` 'active' | 'auto_paused', required: `active` is serving. `auto_paused` means delivery was paused for you and nothing is being sent; it stays paused until you resume it.
    - `pause_message` string: Why this rule is paused and what clears it, in plain words. Present only while the rule is paused.
    - `paused_at` string, date-time, nullable: Start of the current gap. Null while the rule is serving.
    - `pause_reason` string, nullable: Machine readable cause of the current pause, either `deliveries_per_day_cap` (the account reached its daily delivery limit) or `plan_no_webhooks` (the plan does not include webhook delivery). Null while the rule is serving. Render `pause_message` for people.
    - `suppressed_count` integer, required: Matches observed but not delivered since the current pause began. A lower bound, not a total: occurrences no active rule asked for are never looked at.
    - `suppressed_first_at` string, date-time, nullable: First suppressed match of the current pause.
    - `suppressed_last_at` string, date-time, nullable: Most recent suppressed match of the current pause.
    - `last_paused_at` string, date-time, nullable: Start of the last pause that has already ended.
    - `last_resumed_at` string, date-time, nullable: When that pause ended.
    - `last_pause_reason` string, nullable: Cause of the last pause that has already ended, in the same vocabulary as `pause_reason`.
    - `last_suppressed_count` integer, required: Matches suppressed during the last pause that has already ended.
    - `last_suppressed_first_at` string, date-time, nullable: First suppressed match of that pause.
    - `last_suppressed_last_at` string, date-time, nullable: Most recent suppressed match of that pause.

## 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.
- `404`: Not found. `not_found`: the resource id is unknown. `unsupported_for_venue`: the venue does not offer this datatype (`available_on` names where it is served). `route_not_found`: no route matches the path.
- `429`: Rate limit, concurrency limit or monthly credits exceeded. See `error_code`.
- `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)