Webhooks

update_webhook_subscription

destructive write

Update webhook subscription

Copy page

Move a subscription to another endpoint, or point it at a different event topic.

Overview

Changes a webhook subscription topic or destination URL. Only the fields sent change. The signing secret is unchanged and is not returned, so moving a destination does not rotate it. A subscription its integration provider manages is refused rather than changed here. It requires the webhooks:write scope and an idempotency_key. A change to the topic also requires the read scope of the new topic. If a change sends only the URL, it requires the read scope of the current topic. The read scope is orders:read for order:created, products:read for product:created and quotes:read for form:submitted.

Permission

Requires thewebhooks:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHinttrue

Prerequisites

A subscription id from list_webhook_subscriptions.
At least one of topic or url.
A merchant has connected this store and approved the webhooks:write scope and the read scope of the topic that the subscription sends.

Side effects

Changes where future events of that topic are delivered, as outbound HTTPS requests to the new URL.
Leaves the signing secret as it was.
Claims the idempotency_key for at least 24 hours.

Arguments

webhook_idintegerrequired

The subscription id, from list_webhook_subscriptions. An integer, not an opaque string.

topicstring

The event topic to deliver, from list_webhook_event_types. Expected to grow: tolerate unknown values.

One of: product:created, order:created, form:submitted

urlstring

The destination, which must be a public HTTPS address Sign Customiser can reach. A private, loopback or plain-HTTP address is refused.

idempotency_keystringrequired

A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict.

Result

The subscription as it now stands, without its secret. There is no changed-field list: /api/v3 reports none.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

subscriptionobject

The subscription as it now stands. Never carries the signing secret: the secret is readable only when the subscription is created.

subscription.idintegeralways present

subscription.topicstringalways present

subscription.urlstringalways present

subscription.created_atstring or null

subscription.updated_atstring or null

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

Error cases

idempotency_subject_changed

The subscription was deleted after the recorded update. Issue a new key and re-check the resource before writing again.

insufficient_scope

The connection was approved without webhooks:write or without the read scope of the topic. For a topic change, that is the new topic. For a URL-only change, it is the current topic. required_scopes names the missing scope. Ask the merchant to reconnect and approve it.

provider_managed_subscription

The subscription belongs to an integration provider and has to be changed there, not through this connector.

resource_not_found

No subscription with that id belongs to this store. Call list_webhook_subscriptions.

validation_failed

An unknown topic, whose allowed_values the problem repeats, or a URL that is not a public HTTPS address.

Move a subscription to a new endpoint

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_webhook_subscription",
    "arguments": {
      "webhook_id": 42,
      "url": "https://example.com/webhooks/sign-customiser-v2",
      "idempotency_key": "293a4b5c-6d7e-4f01-8c6d-7e8f90123456"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "idempotent_replay": false,
      "subscription": {
        "id": 42,
        "topic": "order:created",
        "url": "https://example.com/webhooks/sign-customiser-v2",
        "created_at": "2026-07-22T00:00:00Z",
        "updated_at": "2026-07-22T00:05:00Z"
      }
    }
  }
}

A provider-managed subscription is refused (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_webhook_subscription",
    "arguments": {
      "webhook_id": 43,
      "url": "https://example.com/webhooks/elsewhere",
      "idempotency_key": "293a4b5c-6d7e-4f01-8c6d-7e8f90123456"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "provider_managed_subscription",
        "title": "Provider-managed subscription",
        "detail": "This subscription is managed by its integration provider and cannot be changed through API v3.",
        "recovery": "This webhook subscription belongs to an integration provider. Change it through that provider instead."
      }
    }
  }
}