---
title: "Update a webhook subscription"
method: PATCH
path: "/v1/webhooks/subscriptions/{id}"
tags: ["Webhooks - Subscriptions"]
---

# Update a webhook subscription

`PATCH /v1/webhooks/subscriptions/{id}`

## Request

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

Edit a rule in place. A configuration you send replaces the stored one and is validated exactly as it was at create; `enabled` switches the rule on or off without touching its configuration. A field you leave out is left alone. Authenticate with an API key or a signed-in dashboard session. Costs no credits.

## Path parameters

- `id` string, uuid, required

## Request body

- WebhookSubscriptionUpdateRequest: Edit a rule in place. Send `filters` (or its alias `config`), `enabled`, or both; a field you leave out is left alone, and other keys are ignored. A configuration is validated exactly as on create. Send `{}` as the configuration to clear it. Changing the configuration never requires deleting and recreating the rule.
  - `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.
  - `enabled` boolean: Your own on and off switch for the rule.

## Response `200`

The updated 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)