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.
Route Metadata
| Field | Value |
|---|---|
| Method | PATCH |
| Path | /v1/webhooks/subscriptions/{id} |
| operationId | updateWebhookSubscription |
| Tag | Webhooks - Subscriptions |
| Family | Webhooks |
| Deprecated or legacy | no |
Human endpoint reference
OpenPATCH /v1/webhooks/subscriptions/{id} for authentication, parameters, responses, and examples.
Request Parameters
Path Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription path parameters",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "Subscription identifier.",
"type": "string",
"format": "uuid",
"example": "3c1f0a52-8d6b-4f0e-9b1a-6f2c4d8e9a10",
"x-parameter-location": "path"
}
}
}
Request Body
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription request body",
"description": "Edit a rule in place. Send either field or both; a field you leave out is left alone. Changing the configuration never requires deleting and recreating the rule.",
"type": "object",
"properties": {
"enabled": {
"description": "Your own on and off switch for the rule.",
"type": "boolean",
"example": true
},
"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 updated subscriptionapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription 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 requestapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription 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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"param": "limit",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"success": false
}
Status 401
Authentication requiredapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription 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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 401,
"error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
"error_code": "unauthorized",
"request_id": "71ed4b6f-63ef-4ae1-a123-07ffa47c1c14",
"success": false
}
Status 404
Resource not foundapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription 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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 404,
"error": "No L4 checkpoint available before requested timestamp",
"error_code": "not_found",
"request_id": "ad7df471-eb8a-477c-bd9f-c685a9825f5b",
"success": false
}
Status 429
Rate limit exceededapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription 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"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 429,
"error": "Rate limit exceeded"
}