openapi: 3.1.0
info:
  title: Computer-Use Agents Webhooks API
  version: 1.0.0
servers:
- url: https://agp.eu.hcompany.ai
  description: Europe
  x-fern-server-name: Eu
- url: https://agp.hcompany.ai
  description: United States
  x-fern-server-name: Us
tags:
- name: Webhooks
paths:
  /api/v2/webhooks:
    post:
      tags:
      - Webhooks
      summary: Create Webhook
      description: Register a webhook. The signing secret is only returned here; store it securely.
      operationId: create_webhook_api_v2_webhooks_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhook'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookWithSecret'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      description: List the organization's webhooks.
      operationId: list_webhooks_api_v2_webhooks_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of items per page
          default: 10
          title: Size
        description: Number of items per page
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - created_at
              - -created_at
              type: string
          - type: 'null'
          description: Sort by field
          default:
          - -created_at
          title: Sort
        description: Sort by field
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_WebhookRecord_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/webhooks/events:
    get:
      tags:
      - Webhooks
      summary: List Webhook Events
      description: List concrete webhook event types clients can subscribe to.
      operationId: list_webhook_events_api_v2_webhooks_events_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WebhookEventTypeDefinition'
                type: array
                title: Response List Webhook Events Api V2 Webhooks Events Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook
      description: Fetch a webhook by id.
      operationId: get_webhook_api_v2_webhooks__webhook_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Webhooks
      summary: Update Webhook
      description: Update a webhook; only provided fields change.
      operationId: update_webhook_api_v2_webhooks__webhook_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhook'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      description: Delete a webhook.
      operationId: delete_webhook_api_v2_webhooks__webhook_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/webhooks/{webhook_id}/rotate:
    post:
      tags:
      - Webhooks
      summary: Rotate Webhook Secret
      description: Replace the signing secret. Only returned here; make your receiver accept both secrets before rotating.
      operationId: rotate_webhook_secret_api_v2_webhooks__webhook_id__rotate_post
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookWithSecret'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/webhooks/{webhook_id}/ping:
    post:
      tags:
      - Webhooks
      summary: Ping Webhook
      description: Send a signed ping event to the webhook and report the receiver's HTTP response.
      operationId: ping_webhook_api_v2_webhooks__webhook_id__ping_post
      security:
      - HTTPBearer: []
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookPingResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WebhookRecord:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        enabled_events:
          items:
            type: string
          type: array
          title: Enabled Events
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        disabled:
          type: boolean
          title: Disabled
        last_delivery_status:
          anyOf:
          - type: string
            enum:
            - succeeded
            - failed
          - type: 'null'
          title: Last Delivery Status
          description: Result of the most recent delivery attempt; null before the first attempt.
        last_delivery_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Delivery Error
          description: What went wrong on the most recent delivery attempt; null when it succeeded.
        last_delivery_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Delivery At
          description: When the most recent delivery attempt happened; null before the first attempt.
        last_success_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Success At
          description: When a delivery last succeeded; null if none has.
        consecutive_failures:
          type: integer
          title: Consecutive Failures
          description: Failed delivery attempts since the last success. The endpoint is automatically disabled when this grows too large; resets to zero on success or re-enable.
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - url
      - enabled_events
      - description
      - disabled
      - created_at
      - updated_at
      title: WebhookRecord
      description: Webhook as returned by reads; the signing secret is never included.
    WebhookWithSecret:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        enabled_events:
          items:
            type: string
          type: array
          title: Enabled Events
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        disabled:
          type: boolean
          title: Disabled
        last_delivery_status:
          anyOf:
          - type: string
            enum:
            - succeeded
            - failed
          - type: 'null'
          title: Last Delivery Status
          description: Result of the most recent delivery attempt; null before the first attempt.
        last_delivery_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Delivery Error
          description: What went wrong on the most recent delivery attempt; null when it succeeded.
        last_delivery_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Delivery At
          description: When the most recent delivery attempt happened; null before the first attempt.
        last_success_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Success At
          description: When a delivery last succeeded; null if none has.
        consecutive_failures:
          type: integer
          title: Consecutive Failures
          description: Failed delivery attempts since the last success. The endpoint is automatically disabled when this grows too large; resets to zero on success or re-enable.
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        secret:
          type: string
          title: Secret
      type: object
      required:
      - id
      - url
      - enabled_events
      - description
      - disabled
      - created_at
      - updated_at
      - secret
      title: WebhookWithSecret
      description: 'Create response: the only time the signing secret is returned.'
    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
    UpdateWebhook:
      properties:
        url:
          anyOf:
          - type: string
            maxLength: 2048
            minLength: 1
          - type: 'null'
          title: Url
        enabled_events:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enabled Events
        description:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Description
        disabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Disabled
      type: object
      title: UpdateWebhook
      description: Partial update; omit a field to leave it unchanged.
    WebhookPingResult:
      properties:
        response_status:
          type: integer
          title: Response Status
          description: HTTP status code returned by the receiving endpoint.
      type: object
      required:
      - response_status
      title: WebhookPingResult
      description: Outcome of a test delivery to a webhook endpoint.
    WebhookEventTypeDefinition:
      properties:
        type:
          type: string
          title: Type
        description:
          type: string
          title: Description
      type: object
      required:
      - type
      - description
      title: WebhookEventTypeDefinition
      description: A webhook event type clients can subscribe to.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Page_WebhookRecord_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WebhookRecord'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[WebhookRecord]
    CreateWebhook:
      properties:
        url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Url
        enabled_events:
          items:
            type: string
          type: array
          title: Enabled Events
          description: Event types delivered to this webhook. '*' subscribes to the session.status_updated firehose; granular session.* types are delivered only when listed explicitly.
          default:
          - '*'
        description:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Description
      type: object
      required:
      - url
      title: CreateWebhook
      description: Register a webhook for the caller's organization.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer