> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook subscription JSON Schema

> Create a webhook subscription JSON Schema contract. Includes parameters, response shapes, examples, and implementation notes from the 0xArchive contract.

Source OpenAPI: 0xArchive API 1.6.1; 168 paths; 190 component schemas.

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.

## Route Metadata

| Field                | Value                        |
| -------------------- | ---------------------------- |
| Method               | `POST`                       |
| Path                 | `/v1/webhooks/subscriptions` |
| operationId          | `createWebhookSubscription`  |
| Tag                  | Webhooks - Subscriptions     |
| Family               | Webhooks                     |
| Deprecated or legacy | no                           |

## Request Body

### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription request body",
  "description": "A new rule. The configuration is validated against the event type's catalog declaration before anything is stored.",
  "type": "object",
  "required": [
    "endpoint_id",
    "event_type"
  ],
  "properties": {
    "endpoint_id": {
      "description": "Endpoint that will receive this rule's deliveries.",
      "type": "string",
      "format": "uuid"
    },
    "event_type": {
      "description": "Event type to subscribe to, from the catalog.",
      "type": "string",
      "example": "market.liquidation"
    },
    "filters": {
      "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"
        }
      }
    }
  }
}
```

## Response Contracts

### Status 200

The new subscription

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription response 200",
  "description": "API response containing one webhook subscription.",
  "type": "object",
  "properties": {
    "data": {
      "description": "A rule: one event type, one configuration, delivered to one endpoint.",
      "type": "object",
      "required": [
        "created_at",
        "enabled",
        "endpoint_id",
        "event_type",
        "filters",
        "id",
        "last_suppressed_count",
        "status",
        "suppressed_count"
      ],
      "properties": {
        "created_at": {
          "description": "When the rule was created.",
          "type": "string",
          "format": "date-time"
        },
        "enabled": {
          "description": "Your own on and off switch. Resuming a paused rule never changes it.",
          "type": "boolean",
          "example": true
        },
        "endpoint_id": {
          "description": "Endpoint that receives this rule's deliveries.",
          "type": "string",
          "format": "uuid"
        },
        "event_type": {
          "description": "Event type this rule subscribes to.",
          "type": "string",
          "example": "market.liquidation"
        },
        "filters": {
          "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"
            }
          }
        },
        "id": {
          "description": "Subscription identifier.",
          "type": "string",
          "format": "uuid"
        },
        "last_pause_reason": {
          "description": "Cause of the last pause that has already ended, in the same vocabulary as `pause_reason`.",
          "type": "string",
          "nullable": true
        },
        "last_paused_at": {
          "description": "Start of the last pause that has already ended.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_resumed_at": {
          "description": "When that pause ended.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_suppressed_count": {
          "description": "Matches suppressed during the last pause that has already ended.",
          "type": "integer",
          "format": "int64",
          "example": 0
        },
        "last_suppressed_first_at": {
          "description": "First suppressed match of that pause.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_suppressed_last_at": {
          "description": "Most recent suppressed match of that pause.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "pause_message": {
          "description": "Why this rule is paused and what clears it, in plain words. Present only while the rule is paused.",
          "type": "string",
          "example": "This rule was paused because the account reached its Pro plan limit of 50000 webhook deliveries in a day. The daily allowance resets at 2026-09-21 00:00 UTC, and a paused rule does not restart with it. Resume it with POST /v1/webhooks/subscriptions/resume."
        },
        "pause_reason": {
          "description": "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.",
          "type": "string",
          "nullable": true,
          "example": "deliveries_per_day_cap"
        },
        "paused_at": {
          "description": "Start of the current gap. Null while the rule is serving.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "status": {
          "description": "`active` is serving. `auto_paused` means delivery was paused for you and nothing is being sent; it stays paused until you resume it.",
          "type": "string",
          "enum": [
            "active",
            "auto_paused"
          ],
          "example": "active"
        },
        "suppressed_count": {
          "description": "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.",
          "type": "integer",
          "format": "int64",
          "example": 0
        },
        "suppressed_first_at": {
          "description": "First suppressed match of the current pause.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "suppressed_last_at": {
          "description": "Most recent suppressed match of the current pause.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": true
    }
  }
}
```

### Status 400

Invalid request

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription 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

```json theme={"theme":"github-dark"}
{
  "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 required

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription 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

```json theme={"theme":"github-dark"}
{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}
```

### Status 404

Resource not found

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription response 404",
  "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

```json theme={"theme":"github-dark"}
{
  "code": 404,
  "error": "Resource not found"
}
```

### Status 429

Rate limit exceeded

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "createWebhookSubscription 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

```json theme={"theme":"github-dark"}
{
  "code": 429,
  "error": "Rate limit exceeded"
}
```