Webhooks

delete_webhook_subscription

destructive write

Delete webhook subscription

Copy page

Stop Sign Customiser delivering one event topic to one endpoint.

Overview

Deletes a webhook subscription and stops delivery to its endpoint. The subscription and its signing secret are gone permanently: recreating it issues a new secret, which every receiver of that endpoint then has to be told about. The call needs confirm: true. A subscription its integration provider manages is refused rather than deleted here. It requires the webhooks:write scope and an idempotency_key.

Permission

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

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHintfalse

Prerequisites

A subscription id from list_webhook_subscriptions.
A merchant has connected this store and approved the webhooks:write scope.

Side effects

Stops delivery of that topic to that endpoint from this point on.
Destroys the signing secret. A recreated subscription gets a new one.
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.

confirmboolean

Must be true to apply the change, because the subscription and its signing secret are destroyed permanently, and a recreated subscription gets a new secret. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

idempotency_keystring

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. A dry run claims no key.

Result

The subscription as it was, so a caller can report what it removed. The secret is not included: it was readable only when the subscription was created.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

webhook_idintegeralways present

deletedboolean

Present and true when the subscription was removed.

subscriptionobject

The subscription as it was, so a caller can report what it removed. Never carries the signing secret.

subscription.idintegeralways present

subscription.topicstringalways present

subscription.urlstringalways present

subscription.created_atstring or null

subscription.updated_atstring or null

Error cases

confirmation_required

Send confirm: true. The signing secret is destroyed with the subscription.

insufficient_scope

The connection was approved without webhooks:write.

missing_idempotency_key

Send idempotency_key. It is required for this write; retrying with the same key replays the original success after the row is gone.

provider_managed_subscription

The subscription belongs to an integration provider and has to be removed there.

resource_not_found

No subscription with that id belongs to this store, or it was already deleted.

Stop delivering order events

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_webhook_subscription",
    "arguments": {
      "webhook_id": 42,
      "confirm": true,
      "idempotency_key": "3a4b5c6d-7e8f-4123-9d7e-8f9012345678"
    }
  }
}

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

Without confirmation nothing is deleted (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_webhook_subscription",
    "arguments": {
      "webhook_id": 42,
      "idempotency_key": "3a4b5c6d-7e8f-4123-9d7e-8f9012345678"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting subscription 42 stops delivery to its endpoint and destroys its signing secret permanently.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}