# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: 'API Evangelist conversational phrasing for Microsoft Azure Custom Speech Web Hooks: API'
  version: 1.0.0
extends: openapi/microsoft-azure-custom-speech-web-hooks-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: 9
- target: $.paths['/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List speech web hooks
      effect: read
      questions:
      - Which web hooks are registered for my Custom Speech subscription?
      - Can I page through my speech web hooks a few at a time?
      instructions:
      - text: List all web hooks on my speech subscription.
      - text: Show {top} web hooks after skipping the first {skip}.
        slots:
          top: query.top
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a speech web hook
      effect: write
      questions:
      - How do I get a callback when my speech transcription or training finishes?
      - Can I sign web hook callbacks with a secret so I can verify the X-MicrosoftSpeechServices-Signature header?
      instructions:
      - text: Register web hook {name} that calls {url} for events {events}.
        slots:
          name: requestBody.displayName
          url: requestBody.webUrl
          events: requestBody.events
      - text: Create a speech web hook posting to {url} named {name}, described as {description}, for {events}.
        slots:
          url: requestBody.webUrl
          name: requestBody.displayName
          description: requestBody.description
          events: requestBody.events
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhooks/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a speech web hook
      effect: read
      questions:
      - What URL and events is one of my speech web hooks configured with?
      - Can I look up a single Custom Speech web hook by its id?
      instructions:
      - text: Get speech web hook {id}.
        slots:
          id: path.id
      - text: Show the callback URL and subscribed events of web hook {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhooks/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a speech web hook
      effect: destructive
      questions:
      - How do I stop speech service callbacks by removing a web hook?
      - Can I delete a Custom Speech web hook I no longer use?
      instructions:
      - text: Delete speech web hook {id}.
        slots:
          id: path.id
      - text: Unregister web hook {id} so it gets no more callbacks.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhooks/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a speech web hook
      effect: write
      questions:
      - Can I change the callback URL or events of an existing speech web hook?
      - What happens to callback signatures if I clear the secret on a web hook?
      instructions:
      - text: Point speech web hook {id} at new URL {url}.
        slots:
          id: path.id
          url: requestBody.webUrl
      - text: Rename web hook {id} to {name} and subscribe it to {events}.
        slots:
          id: path.id
          name: requestBody.displayName
          events: requestBody.events
      method: generated
      generated: '2026-10-01'
- target: $.paths['/webhooks/{id}/ping'].post
  update:
    x-apievangelist-phrasing:
      intent: Ping a web hook via the /ping path
      effect: write
      questions:
      - Is there a /ping path I can POST to so my registered web hook URL gets a ping event?
      - Does the /ping route send the hook's own definition as the payload?
      instructions:
      - text: Ping web hook {hook} using the /ping path.
        slots:
          hook: path.id
      - text: POST to the /ping route of web hook {hook} to confirm its URL responds.
        slots:
          hook: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a web hook via the /test path
      effect: write
      questions:
      - Can I use the /test path to replay each registered event type to my hook URL?
      - Why would the /test route return 204 instead of 200?
      instructions:
      - text: Send test events to web hook {hook} using the /test path.
        slots:
          hook: path.id
      - text: Fire the /test route on web hook {hook} for every event type it listens to.
        slots:
          hook: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{id}:ping'].post
  update:
    x-apievangelist-phrasing:
      intent: Ping a web hook via the :ping action
      effect: write
      questions:
      - Is there a :ping action that sends a ping event to my web hook URL?
      - What signature header comes with a :ping request if the hook has a secret?
      instructions:
      - text: Ping web hook {hook} with the :ping action.
        slots:
          hook: path.id
      - text: Call the colon-style :ping action on hook {hook} to check delivery.
        slots:
          hook: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{id}:test'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a web hook via the :test action
      effect: write
      questions:
      - Can the :test action send a sample request for each of my hook's event types?
      - Where does the :test action get its payload when it replays events?
      instructions:
      - text: Test web hook {hook} with the :test action.
        slots:
          hook: path.id
      - text: Run the colon-style :test action on hook {hook} for all registered events.
        slots:
          hook: path.id
      method: generated
      generated: '2026-09-26'