# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Beehiiv Webhooks API
  version: 1.0.0
extends: openapi/beehiiv-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: 5
- target: $.paths['/publications/{publicationId}/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's webhooks
      effect: read
      questions:
      - Which webhooks are registered on my newsletter?
      - Where are my publication's events currently being delivered?
      instructions:
      - text: List webhooks on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show where {publication} currently delivers webhook events.
        slots:
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a webhook
      effect: write
      questions:
      - How do I get notified at my own URL when someone subscribes?
      - Which event types can I pick when registering a webhook?
      instructions:
      - text: Create a webhook on publication {publication} sending {event_types} events to {url}.
        slots:
          publication: path.publicationId
          event_types: requestBody.event_types
          url: requestBody.url
      - text: Register {url} as a webhook for {event_types} with description {description}.
        slots:
          url: requestBody.url
          event_types: requestBody.event_types
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/webhooks/{endpointId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one webhook
      effect: read
      questions:
      - What events and URL is a specific webhook configured with?
      - Can I look up a single webhook by its endpoint ID?
      instructions:
      - text: Get webhook {webhook} on publication {publication}.
        slots:
          webhook: path.endpointId
          publication: path.publicationId
      - text: Show the URL and events configured on webhook {webhook}.
        slots:
          webhook: path.endpointId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/webhooks/{endpointId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a webhook
      effect: destructive
      questions:
      - How do I stop a webhook from receiving events?
      - Can I remove a webhook subscription from my publication?
      instructions:
      - text: Delete webhook {webhook} from publication {publication}.
        slots:
          webhook: path.endpointId
          publication: path.publicationId
      - text: Stop webhook {webhook} from receiving any more events.
        slots:
          webhook: path.endpointId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/webhooks/{endpointId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a webhook's events or description
      effect: write
      questions:
      - How do I change which events an existing webhook listens for?
      - Can I edit a webhook's description after creating it?
      instructions:
      - text: Update webhook {webhook} on {publication} to listen for {event_types}.
        slots:
          webhook: path.endpointId
          publication: path.publicationId
          event_types: requestBody.event_types
      - text: Change the description of webhook {webhook} to {description}.
        slots:
          webhook: path.endpointId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'