# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Squarespace Commerce Inventory Webhook Subscriptions API
  version: 1.0.0
extends: openapi/squarespace-webhook-subscriptions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/webhook_subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhook subscriptions
      effect: read
      questions:
      - Which webhook endpoints are currently subscribed on my site?
      - How close am I to the 25 active webhook subscription limit?
      instructions:
      - text: List all webhook subscriptions configured for my site.
      - text: Show every webhook subscription with its endpoint URL and topics.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe an endpoint to webhook events
      effect: write
      questions:
      - How do I get notified at my own URL when store events happen on Squarespace?
      - Do I get a secret for verifying signatures when I create a webhook subscription?
      instructions:
      - text: Create a webhook subscription sending {topics} events to {endpointUrl}.
        slots:
          topics: requestBody.topics
          endpointUrl: requestBody.endpointUrl
      - text: Subscribe {endpointUrl} to webhook topics {topics}.
        slots:
          endpointUrl: requestBody.endpointUrl
          topics: requestBody.topics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions/{subscriptionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one webhook subscription
      effect: read
      questions:
      - What endpoint URL and topics does a specific webhook subscription use?
      - Can I see a single webhook subscription's configuration by its ID?
      instructions:
      - text: Get webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Show the endpoint and topics for webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions/{subscriptionId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a webhook's endpoint or topics
      effect: write
      questions:
      - How do I point an existing webhook subscription at a new URL?
      - Can I add or remove event topics on a webhook I already set up?
      instructions:
      - text: Change the endpoint of webhook subscription {subscriptionId} to {endpointUrl}.
        slots:
          subscriptionId: path.subscriptionId
          endpointUrl: requestBody.endpointUrl
      - text: Set the topics of webhook subscription {subscriptionId} to {topics}.
        slots:
          subscriptionId: path.subscriptionId
          topics: requestBody.topics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions/{subscriptionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook subscription
      effect: destructive
      questions:
      - How do I stop receiving webhook notifications at an endpoint?
      - Can I permanently remove a webhook subscription by ID?
      instructions:
      - text: Delete webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Unsubscribe and remove webhook {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions/{subscriptionId}/actions/sendTestNotification'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test webhook notification
      effect: write
      questions:
      - How can I check that my webhook endpoint is reachable before live events arrive?
      - Can I trigger a sample webhook payload to test my handler?
      instructions:
      - text: Send a test notification to webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Fire a test event at the endpoint of webhook {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhook_subscriptions/{subscriptionId}/actions/rotateSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a webhook subscription's secret
      effect: destructive
      questions:
      - How do I generate a new signing secret if my webhook secret may have leaked?
      - Does rotating a webhook secret invalidate the old one immediately?
      instructions:
      - text: Rotate the secret for webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Issue a new signing secret for webhook {subscriptionId} and invalidate the old one.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhook subscriptions (1.0)
      effect: read
      questions:
      - Which webhook subscriptions exist on my site through the 1.0 API?
      - Why does listing webhook subscriptions fail with an API key instead of OAuth?
      instructions:
      - text: List my 1.0 webhook subscriptions.
      - text: Fetch all webhook subscriptions with user agent {user_agent}.
        slots:
          user_agent: header.User-Agent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a webhook subscription (1.0)
      effect: write
      questions:
      - How do I register an HTTPS URL to receive order.create events?
      - What OAuth scopes does my token need for each webhook topic I subscribe to?
      instructions:
      - text: Create a webhook subscription posting to {endpointUrl}.
        slots:
          endpointUrl: requestBody.endpointUrl
      - text: Subscribe {endpointUrl} to the event topics {topics}.
        slots:
          endpointUrl: requestBody.endpointUrl
          topics: requestBody.topics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions/{subscriptionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a webhook subscription (1.0)
      effect: read
      questions:
      - How do I view the details of one webhook subscription?
      - Which topics is a particular webhook subscription listening for?
      instructions:
      - text: Fetch 1.0 webhook subscription {subscriptionId} using my OAuth token.
        slots:
          subscriptionId: path.subscriptionId
      - text: Show the configuration of webhook {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions/{subscriptionId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a webhook subscription (1.0)
      effect: write
      questions:
      - Can I change the URL an existing webhook subscription posts to?
      - How do I update which events an existing webhook is subscribed to?
      instructions:
      - text: Update webhook subscription {subscriptionId} to post to {endpointUrl}.
        slots:
          subscriptionId: path.subscriptionId
          endpointUrl: requestBody.endpointUrl
      - text: Replace the topics on webhook {subscriptionId} with {topics}.
        slots:
          subscriptionId: path.subscriptionId
          topics: requestBody.topics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions/{subscriptionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook subscription (1.0)
      effect: destructive
      questions:
      - How do I delete a webhook subscription I no longer use?
      - Can I remove a webhook subscription with an API key, or only OAuth?
      instructions:
      - text: Delete 1.0 webhook subscription {subscriptionId} using my OAuth token.
        slots:
          subscriptionId: path.subscriptionId
      - text: Remove the webhook {subscriptionId} so it stops receiving events.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions/{subscriptionId}/actions/rotateSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a webhook subscription secret (1.0)
      effect: destructive
      questions:
      - How do I replace the signing secret on a webhook subscription?
      - Is the previous webhook secret still valid after I rotate it?
      instructions:
      - text: Rotate the secret on webhook subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Generate a fresh secret for webhook {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/webhook_subscriptions/{subscriptionId}/actions/sendTestNotification'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test notification for one topic (1.0)
      effect: write
      questions:
      - How do I send a one-off test event for a specific topic to my webhook?
      - Will a failed test webhook notification be retried?
      instructions:
      - text: Fire a one-time {topic} test event at 1.0 webhook {subscriptionId}, with no retries.
        slots:
          topic: requestBody.topic
          subscriptionId: path.subscriptionId
      - text: Test webhook {subscriptionId} with a sample {topic} event.
        slots:
          subscriptionId: path.subscriptionId
          topic: requestBody.topic
      method: generated
      generated: '2026-10-01'