# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One Webhook Subscriptions API
  version: 1.0.0
extends: openapi/integration-os-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: 13
- target: $.paths['/v1/webhooks/subscriptions/by-key/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or reconcile a named webhook listener
      effect: write
      questions:
      - How can I register a webhook listener on every app boot without creating duplicates?
      - Is a signing secret required when I register a listener under a stable name?
      instructions:
      - text: Register listener {key} sending {events} to {url} signed with {secret}.
        slots:
          key: path.key
          events: requestBody.events
          url: requestBody.url
          secret: requestBody.secret
      - text: Reconcile my named listener {key} so it points at {url} for events {events}, secret {secret}.
        slots:
          key: path.key
          url: requestBody.url
          events: requestBody.events
          secret: requestBody.secret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization webhook subscriptions
      effect: read
      questions:
      - Which webhook URLs are subscribed at the organization level?
      - Can I page through my org's webhook subscriptions?
      instructions:
      - text: List webhook subscriptions for organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show page {page} of org {org_id}'s webhook subscriptions.
        slots:
          page: query.page
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a URL to organization events
      effect: write
      questions:
      - How do I get webhooks for events across my whole organization?
      - Can I choose which event types an org webhook receives?
      instructions:
      - text: Subscribe {url} to org {org_id} events {events}.
        slots:
          url: requestBody.url
          org_id: path.org_id
          events: requestBody.events
      - text: Create an organization webhook in {org_id} for {events} at {url} with signing secret {secret}.
        slots:
          org_id: path.org_id
          events: requestBody.events
          url: requestBody.url
          secret: requestBody.secret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List project webhook subscriptions
      effect: read
      questions:
      - Which webhooks are registered inside a specific project?
      - Can I list only one project's webhook subscriptions?
      instructions:
      - text: List webhook subscriptions in project {project_id} of org {org_id}.
        slots:
          project_id: path.project_id
          org_id: path.org_id
      - text: Show {limit} project webhooks per page for project {project_id}, organization {org_id}.
        slots:
          limit: query.limit
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a URL to project events
      effect: write
      questions:
      - How do I receive webhooks only for events inside one project?
      - Do project webhooks fire on organization-level activity?
      instructions:
      - text: Subscribe {url} to project {project_id} events {events} in org {org_id}.
        slots:
          url: requestBody.url
          project_id: path.project_id
          events: requestBody.events
          org_id: path.org_id
      - text: Create a project webhook for {project_id} (org {org_id}) sending {events} to {url}, signed with {secret}.
        slots:
          project_id: path.project_id
          org_id: path.org_id
          events: requestBody.events
          url: requestBody.url
          secret: requestBody.secret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project webhook subscription
      effect: read
      questions:
      - How is a particular project webhook configured?
      - Can I check which events one project subscription listens for?
      instructions:
      - text: Get project webhook subscription {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Show the config of webhook {id} under project {project_id} in organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project webhook subscription
      effect: destructive
      questions:
      - How do I permanently remove a webhook from a project?
      - Is deleting a project webhook permanent, or can it be recovered?
      instructions:
      - text: Delete project webhook subscription {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Remove webhook {id} from project {project_id} of organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a project webhook subscription
      effect: write
      questions:
      - Can I change the delivery URL of an existing project webhook?
      - How do I add event types to a project subscription I already have?
      instructions:
      - text: Point project webhook {id} in project {project_id}, org {org_id}, at {url}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
          url: requestBody.url
      - text: Set events on project {project_id}'s subscription {id} (org {org_id}) to {events}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
          events: requestBody.events
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test event to a project webhook
      effect: write
      questions:
      - How can I check that my receiver handles a project webhook before real events arrive?
      - Can I verify signature validation on a project subscription end-to-end?
      instructions:
      - text: Send a test event to project webhook {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Fire a synthetic delivery at subscription {id} under project {project_id}, organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization webhook subscription
      effect: read
      questions:
      - What URL and event types does an org webhook subscription have?
      - Is a given organization subscription active?
      instructions:
      - text: Get organization webhook subscription {id} in org {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Show org {org_id}'s webhook {id} settings.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization webhook subscription
      effect: destructive
      questions:
      - How do I stop all deliveries to an org webhook by removing it?
      - Is deleting an organization subscription permanent?
      instructions:
      - text: Delete organization webhook subscription {id} in org {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Remove org {org_id}'s webhook {id} for good.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an organization webhook subscription
      effect: write
      questions:
      - Can I pause an org webhook by setting it inactive?
      - How do I rotate the signing secret on an organization subscription?
      instructions:
      - text: Set organization webhook {id} in org {org_id} to active {active}.
        slots:
          id: path.id
          org_id: path.org_id
          active: requestBody.active
      - text: Change the signing secret on org {org_id}'s subscription {id} to {secret}.
        slots:
          org_id: path.org_id
          id: path.id
          secret: requestBody.secret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/subscriptions/organizations/{org_id}/{id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test event to an org webhook
      effect: write
      questions:
      - Can I test an organization webhook without waiting for a real event?
      - Is my org-level receiver reachable and verifying signatures?
      instructions:
      - text: Send a test event to organization webhook {id} in org {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Fire a synthetic delivery at org {org_id}'s subscription {id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'