# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Shopify Admin REST Webhooks API
  version: 1.0.0
extends: openapi/shopify-webhooks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/webhooks.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List my app's webhook subscriptions
      effect: read
      questions:
      - Which webhook subscriptions has my app registered with the store?
      - Can I list only the webhooks subscribed to one topic?
      - What's the most webhooks one page of the list can return?
      instructions:
      - text: List all of my app's webhook subscriptions.
      - text: Show webhooks subscribed to topic {topic}.
        slots:
          topic: query.topic
      - text: List up to {limit} webhooks after ID {since_id}.
        slots:
          limit: query.limit
          since_id: query.since_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/webhooks.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to a store event with a webhook
      effect: write
      questions:
      - How do I get notified at my own URL whenever a store event happens?
      - Can I register a new webhook subscription for an event topic my app cares about?
      instructions:
      - text: Create a webhook subscription from {webhook}.
        slots:
          webhook: requestBody.webhook
      - text: Subscribe my app to store events by registering webhook {webhook}.
        slots:
          webhook: requestBody.webhook
      method: generated
      generated: '2026-09-24'
- target: $.paths['/webhooks/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count webhook subscriptions
      effect: read
      questions:
      - How many webhook subscriptions does my app currently have?
      - Can I count the webhooks registered for a single topic?
      instructions:
      - text: Count my app's webhook subscriptions.
      - text: Count the webhooks subscribed to {topic}.
        slots:
          topic: query.topic
      method: generated
      generated: '2026-09-24'
- target: $.paths['/webhooks/{webhook_id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one webhook subscription
      effect: read
      questions:
      - Where is a particular webhook subscription sending its events?
      - Can I look up a single webhook's topic and format by its ID?
      instructions:
      - text: Show webhook subscription {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      - text: Get the details of webhook {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/webhooks/{webhook_id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Change an existing webhook subscription
      effect: write
      questions:
      - My endpoint moved; can I point an existing webhook at a new address?
      - What can I change on a webhook subscription I already created?
      instructions:
      - text: Update webhook {webhook_id} with {webhook}.
        slots:
          webhook_id: path.webhook_id
          webhook: requestBody.webhook
      - text: Edit the existing subscription {webhook_id} using settings {webhook}.
        slots:
          webhook_id: path.webhook_id
          webhook: requestBody.webhook
      method: generated
      generated: '2026-09-24'
- target: $.paths['/webhooks/{webhook_id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook subscription
      effect: destructive
      questions:
      - How can I stop receiving events for a webhook I no longer need?
      - Is unsubscribing a webhook permanent?
      instructions:
      - text: Delete webhook subscription {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      - text: Unsubscribe webhook {webhook_id} so it stops firing.
        slots:
          webhook_id: path.webhook_id
      method: generated
      generated: '2026-09-24'