# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Webhooks API
  version: 1.0.0
extends: openapi/optimizely-webhooks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/{clientId}/webhooks/{webhookId}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a client's event webhook
      effect: write
      questions:
      - How do I switch on a webhook so it starts sending event data for my client account?
      - Can I reactivate a webhook that I paused earlier?
      instructions:
      - text: Activate webhook {webhookId} for client {clientId}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
      - text: Start sending event data on webhook {webhookId} in client {clientId}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a client's event webhooks
      effect: read
      questions:
      - Which webhooks are set up for my client account and are they active?
      - Can I sort my client's webhooks and page through them with offset and limit?
      instructions:
      - text: List all webhooks for client {clientId}.
        slots:
          clientId: path.clientId
      - text: Show {limit} webhooks for client {clientId} sorted by {sort}.
        slots:
          limit: query.limit
          clientId: path.clientId
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an event webhook for a client
      effect: write
      questions:
      - How do I create a webhook that pushes event data to my URL for a client account?
      - Can a client webhook use basic auth when calling my target URL?
      instructions:
      - text: Create a {type} webhook for client {clientId} that posts {format} data to {targetUrl}.
        slots:
          type: requestBody.type
          clientId: path.clientId
          format: requestBody.format
          targetUrl: requestBody.targetUrl
      - text: Set up a client {clientId} webhook to {targetUrl} with basic auth user {basicAuthUsername}.
        slots:
          clientId: path.clientId
          targetUrl: requestBody.targetUrl
          basicAuthUsername: requestBody.basicAuthUsername
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks/{webhookId}/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a client's event webhook
      effect: write
      questions:
      - How do I stop a webhook from sending event data without deleting it?
      - Can I temporarily turn off a client webhook?
      instructions:
      - text: Deactivate webhook {webhookId} for client {clientId}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
      - text: Stop event delivery on webhook {webhookId} in client {clientId} but keep it configured.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks/{webhookId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a client webhook's target or format
      effect: write
      questions:
      - How do I point an existing client webhook at a new target URL?
      - Can I change the data format a client webhook sends?
      instructions:
      - text: Update webhook {webhookId} in client {clientId} to send to {targetUrl}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
          targetUrl: requestBody.targetUrl
      - text: Switch client {clientId} webhook {webhookId} to {format} format.
        slots:
          clientId: path.clientId
          webhookId: path.webhookId
          format: requestBody.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks/{webhookId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a client's event webhook
      effect: destructive
      questions:
      - How do I permanently remove a webhook from my client account?
      - What happens if I delete a client webhook instead of deactivating it?
      instructions:
      - text: Delete webhook {webhookId} from client {clientId}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
      - text: Permanently remove client {clientId}'s webhook {webhookId}.
        slots:
          clientId: path.clientId
          webhookId: path.webhookId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/webhooks/{webhookId}/verify'].get
  update:
    x-apievangelist-phrasing:
      intent: Test a client webhook against its target URL
      effect: read
      questions:
      - How do I check that my webhook's target URL is ready before going live?
      - Can I send a few test events for a mailing to verify a webhook?
      instructions:
      - text: Verify webhook {webhookId} in client {clientId} using mailing {mailingId}.
        slots:
          webhookId: path.webhookId
          clientId: path.clientId
          mailingId: query.mailingId
      - text: Send {numberOfEvents} test events from mailing {mailingId} to webhook {webhookId} of client {clientId}.
        slots:
          numberOfEvents: query.numberOfEvents
          mailingId: query.mailingId
          webhookId: path.webhookId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List registered content webhooks
      effect: read
      questions:
      - What webhooks are registered on the /api/webhooks endpoint for content events?
      - Can I see every webhook handler along with its topics and filters?
      instructions:
      - text: List all webhooks registered under /api/webhooks.
      - text: Show me every registered webhook handler and the topics it listens to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a webhook for topic events
      effect: write
      questions:
      - How do I register a webhook that listens only to certain topics?
      - If I leave the filter empty, will the webhook receive every event?
      instructions:
      - text: Register a webhook that sends request {request} for topics {topics}.
        slots:
          request: requestBody.request
          topics: requestBody.topics
      - text: Add a webhook handler with request {request} and filters {filters}.
        slots:
          request: requestBody.request
          filters: requestBody.filters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/webhooks/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a registered topic webhook
      effect: write
      questions:
      - How do I change the topics or filters of a webhook I already registered?
      - Can I disable a registered webhook handler without deleting it?
      instructions:
      - text: Update registered webhook {id} to listen to topics {topics}.
        slots:
          id: path.id
          topics: requestBody.topics
      - text: Set disabled to {disabled} on webhook handler {id} with request {request}.
        slots:
          disabled: requestBody.disabled
          id: path.id
          request: requestBody.request
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/webhooks/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unregister a topic webhook
      effect: destructive
      questions:
      - How do I unregister a webhook handler from /api/webhooks?
      - Can I remove a registered content webhook by its id?
      instructions:
      - text: Unregister webhook handler {id}.
        slots:
          id: path.id
      - text: Delete the registered /api/webhooks entry {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhooks in an experimentation project
      effect: read
      questions:
      - Which webhooks exist in my Optimizely experimentation project?
      - Can I page through a project's webhooks using a page token?
      instructions:
      - text: List the webhooks in project {project_id}.
        slots:
          project_id: path.project_id
      - text: Show {per_page} webhooks per page for project {project_id}.
        slots:
          per_page: query.per_page
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a webhook in a project
      effect: write
      questions:
      - How do I get notified at my URL when events happen in a project?
      - What name, description and events must a new project webhook have?
      instructions:
      - text: Create a webhook {name} in project {project_id} that calls {url} on events {events}.
        slots:
          name: requestBody.name
          project_id: path.project_id
          url: requestBody.url
          events: requestBody.events
      - text: Add a project {project_id} webhook to {url} described as {description}.
        slots:
          project_id: path.project_id
          url: requestBody.url
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{webhook_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project webhook's details
      effect: read
      questions:
      - How do I see all the properties of a single project webhook?
      - Which events and URL is a particular project webhook configured with?
      instructions:
      - text: Get project webhook {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      - text: Show the URL and events for webhook {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{webhook_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project webhook
      effect: destructive
      questions:
      - How do I remove a webhook from an experimentation project?
      - Can I delete a project webhook knowing only its webhook_id?
      instructions:
      - text: Delete project webhook {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      - text: Remove the experimentation webhook {webhook_id}.
        slots:
          webhook_id: path.webhook_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/webhooks/{webhook_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a project webhook
      effect: write
      questions:
      - How do I change the URL or subscribed events of a project webhook?
      - Can I rename an existing experimentation webhook?
      instructions:
      - text: Update project webhook {webhook_id} to call {url}.
        slots:
          webhook_id: path.webhook_id
          url: requestBody.url
      - text: Change the events on project webhook {webhook_id} to {events}.
        slots:
          webhook_id: path.webhook_id
          events: requestBody.events
      method: generated
      generated: '2026-09-26'