Webhooks

list_webhook_subscriptions

read

List webhook subscriptions

Copy page

See where a Store already sends events, and obtain the subscription ids the update and delete tools take.

Overview

Lists the connected Store webhook subscriptions with each one id, topic, destination URL and timestamps. Signing secrets are never included: a subscription secret is shown once, at creation, and cannot be read back. Results are paginated. It requires the webhooks:read scope and has no side effects.

Permission

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

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A merchant has connected this store and approved the webhooks:read scope.

Arguments

limitinteger

How many subscriptions to return per page, between 1 and 100. Defaults to 20.

cursorstring

The opaque next_cursor value from the previous page. Omit it for the first page.

Result

Up to `limit` subscriptions plus the cursor for the next page. Never a signing secret.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

subscriptionsarray of objectalways present

The page of subscriptions. Never a signing secret.

subscriptions[].idintegeralways present

subscriptions[].topicstringalways present

subscriptions[].urlstringalways present

subscriptions[].created_atstring or null

subscriptions[].updated_atstring or null

paginationobjectalways present

pagination.has_morebooleanalways present

pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without webhooks:read.

invalid_cursor

The cursor was altered or reused; restart with no cursor.

The store registered endpoints

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_webhook_subscriptions",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "subscriptions": [
        {
          "id": 42,
          "topic": "product:created",
          "url": "https://example.com/webhooks/sign-customiser",
          "created_at": "2026-07-22T00:00:00Z",
          "updated_at": "2026-07-22T00:00:00Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}

A connection holding only webhooks:write (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_webhook_subscriptions",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [list_webhook_subscriptions] requires the webhooks:read scope, which this connection was not granted.",
        "recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the connector and approve the scope named in required_scopes. Do not retry this call.",
        "required_scopes": [
          "webhooks:read"
        ],
        "granted_scopes": [
          "webhooks:write"
        ]
      }
    }
  }
}