Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.offthehook.dev/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint to replace all mutable fields on an existing subscription. Because this is a PUT, you must supply every field — any field you omit will be reset to its default value. Address filters and the signing secret are never affected by this operation; use the addresses endpoint to modify filters and the rotate endpoint to issue a new secret.

​
Request

PUT /v1/subscriptions/:id

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer oth_YOUR_API_KEY
Content-TypeYesapplication/json

​
Path parameters

​
id
string
required
The subscription ID to update. Always starts with sub_.

​
Body

​
destination
object
required
Replacement webhook delivery target.
​
events
string[]
required
Replacement list of event kinds to receive. Must be non-empty.
​
status
string
required
"enabled" or "disabled".
​
description
string
required
Human-readable label. Pass an empty string to clear it.

​
Example request

curl -X PUT https://api.offthehook.dev/v1/subscriptions/sub_2QkP9aB7xN... \
  -H "Authorization: Bearer oth_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "https",
      "url": "https://your-server.example.com/webhooks-v2"
    },
    "events": ["wallet.transfer.broadcasted"],
    "status": "enabled",
    "description": "Updated description"
  }'

​
Response

200 OK Returns the updated subscription resource. The destination.secret field is not present in the response. The filters.addresses array will be empty in the response body (address filters are unaffected by this call — use GET /v1/subscriptions/:id to see current filters). 
{
  "id": "sub_2QkP9aB7xN...",
  "destination": { "type": "https", "url": "https://your-server.example.com/webhooks-v2" },
  "events": ["wallet.transfer.broadcasted"],
  "filters": { "addresses": [] },
  "status": "enabled",
  "description": "Updated description",
  "dateCreated": "2026-05-08T12:00:00Z",
  "dateUpdated": "2026-05-08T12:01:00Z"
}

​
Response fields

​
id
string
required
Unique subscription identifier, prefixed with sub_.
​
destination
object
required
Updated delivery target. destination.secret is not included.
​
events
string[]
required
The updated list of event kinds.
​
filters
object
required
Contains an empty addresses array. Your existing address filters remain in place — this endpoint does not modify them.
​
status
string
required
Updated status: "enabled" or "disabled".
​
description
string
required
Updated human-readable label.
​
dateCreated
string
required
ISO 8601 creation timestamp. Unchanged by updates.
​
dateUpdated
string
required
ISO 8601 timestamp of this update.

​
Errors

CodeDescription
not_foundNo subscription with the given ID exists under your API key.
invalid_requestA required field is missing, contains an invalid value, or the JSON is malformed.
ssrf_blockedThe new destination.url resolved to a private or reserved IP range.
unsupported_eventOne or more entries in events are not recognized.
description_too_longThe description field exceeds the maximum allowed length.
unauthorizedThe Authorization header is missing or the API key is invalid.