Clarity Webhooks Admin API

openapi: 3.2.0
info:
  title: Fast Webhooks Admin API
  version: 0.1.0
tags:
- name: webhooks_admin
paths:
  /api/admin/v1/webhooks:
    get:
      tags:
      - webhooks_admin
      summary: List Webhooks
      description: Every webhook configured for the project — direct subscriptions and flow bindings alike.
      operationId: list_webhooks_api_admin_v1_webhooks_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookDTO'
                title: Response List Webhooks Api Admin V1 Webhooks Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - webhooks_admin
      summary: Create Webhook
      description: 'Subscribe a URL to the project''s feedback stream.


        Idempotent on ``webhook_url``: re-posting the same target updates its name/filters in

        place and returns the existing subscription instead of creating a second one that would

        double-deliver. Callers that enable/disable repeatedly (a workflows trigger''s

        ``onEnable``) therefore never accumulate duplicates.'
      operationId: create_webhook_api_admin_v1_webhooks_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__routers__webhooks_admin__AdminCreateWebhookRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDTO'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/webhooks/{webhook_id}:
    delete:
      tags:
      - webhooks_admin
      summary: Delete Webhook
      description: 'Unsubscribe. Deleting an id the project doesn''t have is a no-op (204), so a

        subscriber''s teardown stays idempotent. Any workflow behind the URL is left

        alone — this contour never owned it.'
      operationId: delete_webhook_api_admin_v1_webhooks__webhook_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    src__routers__webhooks_admin__AdminCreateWebhookRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Shown in the webhooks list
        webhook_url:
          type: string
          title: Webhook Url
          description: Absolute http(s) URL on a publicly routable host
        filters:
          items:
            $ref: '#/components/schemas/WebhookFilter'
          type: array
          title: Filters
          description: AND-ed; an empty list delivers every ingested ticket
      type: object
      required:
      - project_id
      - name
      - webhook_url
      title: AdminCreateWebhookRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WebhookDTO:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        filters:
          items:
            $ref: '#/components/schemas/WebhookFilter'
          type: array
          title: Filters
        webhook_url:
          type: string
          title: Webhook Url
        workflow_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workflow Id
      type: object
      required:
      - id
      - name
      - filters
      - webhook_url
      title: WebhookDTO
    WebhookFilter:
      properties:
        key:
          type: string
          title: Key
        type:
          type: string
          title: Type
        operator:
          type: string
          title: Operator
        values:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Values
        value:
          anyOf:
          - {}
          - type: 'null'
          title: Value
      type: object
      required:
      - key
      - type
      - operator
      title: WebhookFilter
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic