QA Wolf Webhooks API

openapi: 3.1.0
info:
  title: QA Wolf REST CI Webhooks API
  version: v0
  description: 'The QA Wolf REST API provides direct HTTP access to core platform actions: triggering test runs on deployment, polling run outcomes to gate CI pipelines, and generating signed URLs to upload executable run inputs. QA Wolf recommends the @qawolf/ci-sdk library for most use cases rather than calling these endpoints directly. This specification was generated by the API Evangelist enrichment pipeline from QA Wolf''s published REST API reference documentation; it is a faithful capture of documented behavior, not a provider-published OpenAPI file.'
  x-provenance:
    generated: '2026-07-20'
    method: generated
    source: https://docs.qawolf.com/qawolf/rest-overview.md
    note: Generated from published docs; QA Wolf does not publish an OpenAPI file.
  contact:
    name: QA Wolf
    email: hello@qawolf.com
    url: https://docs.qawolf.com/qawolf/rest-overview
servers:
- url: https://app.qawolf.com
  description: QA Wolf platform
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Deployment and environment lifecycle notifications to QA Wolf
paths:
  /api/webhooks/deploy_success:
    post:
      tags:
      - Webhooks
      operationId: notifyDeploySuccess
      summary: Notify QA Wolf of a successful deployment
      description: Notify QA Wolf of a successful deployment to trigger a test run. Match rules on the QA Wolf side decide which triggers fire and which flows run.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploySuccessRequest'
      responses:
        '200':
          description: Request accepted. Inspect the body to confirm run creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploySuccessResponse'
        '401':
          description: Invalid API key
        '403':
          description: Disabled team
        '405':
          description: Wrong HTTP method
  /api/webhooks/environment_terminated:
    post:
      tags:
      - Webhooks
      operationId: notifyEnvironmentTerminated
      summary: Notify QA Wolf that an ephemeral environment has been terminated
      description: Notify QA Wolf that an ephemeral environment has been terminated. Stops all runs targeting the environment and requests flow promotion to the static base environment. The environment will show as "closed" in QA Wolf.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentTerminatedRequest'
      responses:
        '200':
          description: Termination accepted
        '401':
          description: Invalid API key
        '403':
          description: Disabled team
components:
  schemas:
    DeploySuccessResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              created_suite_id:
                type: string
              duplicate_suite_id:
                type: string
              trigger_id:
                type: string
              failure_reason:
                type: string
    EnvironmentTerminatedRequest:
      type: object
      properties:
        deployment_url:
          type: string
          description: The URL of the ephemeral environment that was terminated.
        branch:
          type: string
    DeploySuccessRequest:
      type: object
      description: Fields describing a successful deployment that should trigger runs.
      properties:
        branch:
          type: string
          description: Git branch name, used for UI display and PR matching.
        sha:
          type: string
          description: Git commit SHA, used for GitHub checks and commit links.
        deployment_type:
          type: string
          description: Required if a trigger is configured to match deployment types.
        deployment_url:
          type: string
          description: Overrides the environment URL; exposed to flows as process.env.URL.
        hosting_service:
          type: string
          enum:
          - GitHub
          - GitLab
          default: GitHub
          description: Hosting service for commit links.
        commit_url:
          type: string
          description: Makes the commit id clickable when no repo is configured.
        variables:
          type: object
          additionalProperties: true
          description: Environment variable overrides applied to the triggered runs.
        deduplication_key:
          type: string
          description: Controls run cancellation / deduplication behavior.
        ephemeral_environment:
          type: boolean
          description: Use with deployment_url for non-integrated ephemeral deployments.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token using the workspace API key (QAWOLF_API_KEY). Find the key in the platform under Workspace Settings -> Integrations -> API Access.