Create a webhook subscription JSON Schema

{
  "$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"
        }
      }
    }
  }
}

{
  "$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
    }
  }
}

{
  "$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"
    }
  }
}

{
  "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"
}

{
  "$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"
    }
  }
}

{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}

{
  "$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"
    }
  }
}

{
  "code": 404,
  "error": "Resource not found"
}

{
  "$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"
    }
  }
}

{
  "code": 429,
  "error": "Rate limit exceeded"
}