# 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 Relay API
  version: 1.0.0
extends: openapi/integration-os-webhook-relay-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: 16
- target: $.paths['/v1/webhooks/relay'].get
  update:
    x-apievangelist-phrasing:
      intent: List my webhook relay endpoints
      effect: read
      questions:
      - Which webhook relay endpoints have been set up under my key?
      - Can I page through relay endpoints across my personal, org or project scope?
      instructions:
      - text: List my webhook relay endpoints.
      - text: Show page {page} of relay endpoints, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a webhook relay endpoint on a connection
      effect: write
      questions:
      - How do I start receiving a connected platform's webhooks for one of my connections?
      - Can I choose which event types trigger a relay endpoint when I create it?
      - Does a new relay endpoint start receiving events immediately, or does it need activating?
      instructions:
      - text: Create a webhook relay endpoint for connection {connectionKey}.
        slots:
          connectionKey: requestBody.connectionKey
      - text: Register a relay endpoint on connection {connectionKey} filtered to events {eventFilters}.
        slots:
          connectionKey: requestBody.connectionKey
          eventFilters: requestBody.eventFilters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/config/{conn_def_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get webhook setup instructions for a connector
      effect: read
      questions:
      - What URL do I paste into the upstream platform to set up webhook relay for a connector?
      - Which fields and steps does a connector need before its webhooks can be relayed?
      instructions:
      - text: Show the webhook relay setup instructions for connector definition {conn_def_id}.
        slots:
          conn_def_id: path.conn_def_id
      - text: Get the relay inbound URL and required fields for connector {conn_def_id}.
        slots:
          conn_def_id: path.conn_def_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/event-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List the webhook event types a platform sends
      effect: read
      questions:
      - Which webhook event types can a given platform deliver through the relay?
      - Can I search a platform's event types by keyword to build a picker?
      instructions:
      - text: List the webhook event types platform {platform} can deliver.
        slots:
          platform: query.platform
      - text: Find {platform} event types matching "{search}".
        slots:
          platform: query.platform
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List inbound webhook events the relay received
      effect: read
      questions:
      - What webhook deliveries has the relay received from upstream platforms?
      - Can I filter received relay events by connection, event type or time range?
      instructions:
      - text: List inbound webhook events received by the relay.
      - text: Show relay events of type {eventType} on connection {connectionId} received after {after}.
        slots:
          eventType: query.eventType
          connectionId: query.connectionId
          after: query.after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/events/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one inbound webhook event and its payload
      effect: read
      questions:
      - How do I see the raw payload an upstream platform sent for a specific webhook event?
      - Can I inspect a single received relay event by its ID?
      instructions:
      - text: Get relay event {id} with its raw payload.
        slots:
          id: path.id
      - text: Show me what the upstream platform sent in inbound event {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/events/{id}/deliveries'].get
  update:
    x-apievangelist-phrasing:
      intent: List delivery attempts for a relay event
      effect: read
      questions:
      - Why did a received webhook event not reach one of my endpoints?
      - Can I see every retry the relay made when forwarding a particular event?
      instructions:
      - text: List the delivery attempts made for relay event {id}.
        slots:
          id: path.id
      - text: Show which endpoints inbound event {id} was forwarded to and how each try went.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/incoming/{platform}/{connection_key}'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept an inbound webhook from a platform
      effect: write
      questions:
      - What is the inbound URL upstream platforms post webhooks to for a connection?
      - Does the relay verify the signature of an incoming webhook before forwarding it?
      instructions:
      - text: Deliver an inbound webhook from platform {platform} for connection {connection_key}.
        slots:
          platform: path.platform
          connection_key: path.connection_key
      - text: Post a test upstream delivery to the relay's incoming URL for {platform} connection {connection_key}.
        slots:
          platform: path.platform
          connection_key: path.connection_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/organizations/{org_id}/projects/{project_id}/{id}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a project relay endpoint
      effect: write
      questions:
      - How do I turn on a relay endpoint that belongs to a project so events start flowing?
      - Can I supply a webhook secret when activating a project-scoped relay endpoint?
      instructions:
      - text: Activate relay endpoint {id} in project {project_id}, org {org_id}, with actions {actions}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
          actions: requestBody.actions
      - text: Start event flow for project {project_id} relay {id} in org {org_id} using actions {actions} and secret {webhookSecret}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
          actions: requestBody.actions
          webhookSecret: requestBody.webhookSecret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/organizations/{org_id}/{id}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate an organization relay endpoint
      effect: write
      questions:
      - How do I activate a relay endpoint owned by my organization rather than a project?
      - What actions must I pass to switch on an org-level relay endpoint?
      instructions:
      - text: Activate organization {org_id} relay endpoint {id} with actions {actions}.
        slots:
          org_id: path.org_id
          id: path.id
          actions: requestBody.actions
      - text: Register org-level relay {id} in {org_id} upstream, running {actions} on each event.
        slots:
          id: path.id
          org_id: path.org_id
          actions: requestBody.actions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/platforms'].get
  update:
    x-apievangelist-phrasing:
      intent: List platforms that can send relayed webhooks
      effect: read
      questions:
      - Which platforms can I receive inbound webhooks from through the relay?
      - How many event types does each relay-supported platform emit?
      instructions:
      - text: List the platforms supported by webhook relay.
      - text: Show each relay platform with its count of event types.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a relay endpoint's configuration
      effect: read
      questions:
      - What event types and actions is a particular relay endpoint configured with?
      - Can I check whether a relay endpoint is currently active?
      instructions:
      - text: Get relay endpoint {id}.
        slots:
          id: path.id
      - text: Show the connection, subscribed events and active status of relay endpoint {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook relay endpoint
      effect: destructive
      questions:
      - How do I stop relaying webhooks to an endpoint and remove it?
      - Will events already in flight still be delivered after I delete a relay endpoint?
      instructions:
      - text: Delete relay endpoint {id}.
        slots:
          id: path.id
      - text: Remove relay endpoint {id} and deactivate its upstream webhook.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a webhook relay endpoint
      effect: write
      questions:
      - Can I change which event types an existing relay endpoint listens for?
      - How do I pause a relay endpoint without deleting it?
      instructions:
      - text: Change relay endpoint {id} to filter events {eventFilters}.
        slots:
          id: path.id
          eventFilters: requestBody.eventFilters
      - text: Set relay endpoint {id} active to {active}.
        slots:
          id: path.id
          active: requestBody.active
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/{id}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a relay endpoint so events flow
      effect: write
      questions:
      - Why isn't my newly created relay endpoint receiving any events?
      - Which actions do I specify when activating my own relay endpoint?
      instructions:
      - text: Activate relay endpoint {id} with actions {actions}.
        slots:
          id: path.id
          actions: requestBody.actions
      - text: Register my relay endpoint {id} upstream using actions {actions} and webhook secret {webhookSecret}.
        slots:
          id: path.id
          actions: requestBody.actions
          webhookSecret: requestBody.webhookSecret
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/webhooks/relay/{id}/deliveries'].get
  update:
    x-apievangelist-phrasing:
      intent: List deliveries sent to a relay endpoint
      effect: read
      questions:
      - Are deliveries to a specific relay endpoint succeeding or failing?
      - Can I see the recent traffic a relay endpoint has received?
      instructions:
      - text: List the deliveries attempted against relay endpoint {id}.
        slots:
          id: path.id
      - text: Show recent traffic and failures for endpoint {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'