Webhooks

create_webhook_subscription

write

Create webhook subscription

Copy page

Point one Sign Customiser event topic at an endpoint the merchant runs.

Overview

Subscribes an HTTPS endpoint the merchant controls to one event topic, so Sign Customiser will POST to it when that event occurs. The topic must be one list_webhook_event_types returns, and the URL must be a public HTTPS address. The response includes the signing secret exactly once: it is never readable again, so it has to be stored at that moment. 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

destructiveHintfalse

idempotentHinttrue

openWorldHinttrue

Prerequisites

A topic from list_webhook_event_types.
A public HTTPS URL the merchant controls. A private or non-HTTPS address is refused.
A merchant has connected this store and approved the webhooks:write scope.

Side effects

Creates one subscription, so future events of that topic are delivered to the URL as outbound HTTPS requests.
Issues a signing secret that is returned once and cannot be read back.
Claims the idempotency_key for at least 24 hours.

Arguments

topicstringrequired

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

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

urlstringrequired

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

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 created subscription and its show-once signing secret. The secret is returned by this tool and by an exact idempotent replay, and by nothing else.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

subscriptionobject

The created subscription. Its secret is a sibling member, not part of this object.

subscription.idintegeralways present

subscription.topicstringalways present

subscription.urlstringalways present

subscription.created_atstring or null

subscription.updated_atstring or null

secretstring

The show-once signing credential, used to verify the HMAC on every delivery. Returned by this tool and by an exact idempotent replay only. Store it; do not repeat it into a transcript.

idempotent_replayboolean

True when this call replayed an earlier write carrying the same idempotency_key rather than creating a second subscription.

Error cases

idempotency_key_conflict

That key was used with different arguments. Re-send the original arguments or issue a new key; a new key creates a second subscription with its own secret.

insufficient_scope

The connection was approved without webhooks:write.

missing_idempotency_key

Send idempotency_key. It is required for this write.

validation_failed

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

Deliver order events to the merchant endpoint

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_webhook_subscription",
    "arguments": {
      "topic": "order:created",
      "url": "https://example.com/webhooks/sign-customiser",
      "idempotency_key": "18293a4b-5c6d-4e0f-9b5c-6d7e8f901234"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "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"
      },
      "secret": "the-show-once-signing-secret",
      "idempotent_replay": false
    }
  }
}

A URL that is not public HTTPS (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_webhook_subscription",
    "arguments": {
      "topic": "order:created",
      "url": "http://localhost/webhooks",
      "idempotency_key": "18293a4b-5c6d-4e0f-9b5c-6d7e8f901234"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The url must be a public HTTPS address Sign Customiser can reach.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "pointer": "/url"
      }
    }
  }
}