# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Webhook Subscriptions API
  version: 1.0.0
extends: openapi/square-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: 8
- target: $.paths['/v2/webhooks/event-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscribable webhook event types
      effect: read
      questions:
      - Which webhook events can my app subscribe to?
      - Are the available webhook event types different by API version?
      instructions:
      - text: List all webhook event types.
      - text: Show webhook event types available in API version {api_version}.
        slots:
          api_version: query.api_version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List my webhook subscriptions
      effect: read
      questions:
      - What webhook subscriptions does my application have?
      - Can I include disabled webhook subscriptions in the list?
      instructions:
      - text: List my webhook subscriptions.
      - text: 'Show webhook subscriptions including disabled ones: {include_disabled}.'
        slots:
          include_disabled: query.include_disabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to webhook events
      effect: write
      questions:
      - How do I start receiving Square webhook notifications at my URL?
      - Can I create a webhook subscription for specific event types?
      instructions:
      - text: Create webhook subscription {subscription}.
        slots:
          subscription: requestBody.subscription
      - text: 'Subscribe my endpoint to these webhook events: {subscription}.'
        slots:
          subscription: requestBody.subscription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions/{subscription_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a webhook subscription
      effect: read
      questions:
      - What events and URL does a given webhook subscription use?
      - How can I check if one webhook subscription is enabled?
      instructions:
      - text: Get webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Show the settings of webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions/{subscription_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a webhook subscription
      effect: write
      questions:
      - How do I change the notification URL or events of a webhook subscription?
      - Can I disable a webhook subscription without deleting it?
      instructions:
      - text: Update webhook subscription {subscription_id} with {subscription}.
        slots:
          subscription_id: path.subscription_id
          subscription: requestBody.subscription
      - text: Change the events on webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions/{subscription_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook subscription
      effect: destructive
      questions:
      - How do I stop a webhook subscription for good?
      - What's the way to remove a webhook endpoint I no longer use?
      instructions:
      - text: Delete webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Remove webhook subscription {subscription_id} permanently.
        slots:
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions/{subscription_id}/signature-key'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a webhook signature key
      effect: write
      questions:
      - How do I rotate the signing key used to verify my webhooks?
      - Can I replace a webhook subscription's signature key if it leaked?
      instructions:
      - text: Rotate the signature key for webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Generate a new signing key on webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/webhooks/subscriptions/{subscription_id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test webhook event
      effect: write
      questions:
      - How can I check that my webhook endpoint is receiving events?
      - Can I send a test event of a particular type to my notification URL?
      instructions:
      - text: Send a test event to webhook subscription {subscription_id}.
        slots:
          subscription_id: path.subscription_id
      - text: Test webhook subscription {subscription_id} with a {event_type} event.
        slots:
          subscription_id: path.subscription_id
          event_type: requestBody.event_type
      method: generated
      generated: '2026-10-01'