Webhooks

list_webhook_event_types

read

List webhook event types

Copy page

Find the exact topic string a webhook subscription needs, rather than guessing its spelling.

Overview

Lists the event topics a webhook subscription can be created for, each with its stable topic string, a one-line description of when it fires, and a link to the signature-verification guide. Creating a subscription takes one of these topics, so this is the discovery call before it. The catalogue is server-owned and returned in one complete page. Topic values are expected to grow. 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

This tool takes no arguments.

Result

The complete topic catalogue in one page. Example payloads are omitted; the signature-verification guide is linked instead. Catalogue visibility does not by itself establish delivery eligibility for a Store.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

event_typesarray of objectalways present

The complete topic catalogue.

event_types[].topicstringalways present

The topic string a subscription is created with. Expected to grow: tolerate unknown values.

event_types[].descriptionstringalways present

event_types[].signature_verification_urlstring or null

Error cases

insufficient_scope

The connection was approved without webhooks:read.

Read the topic catalogue

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "event_types": [
        {
          "topic": "product:created",
          "description": "Sent after Sign Customiser creates a customer-designed product.",
          "signature_verification_url": "https://www.signcustomiser.com/help/integrations/subscribe-to-webhooks/"
        }
      ]
    }
  }
}

A connection without webhooks:read (error)

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [list_webhook_event_types] 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"
        ]
      }
    }
  }
}