openapi: 3.0.3
info:
  title: Willo Integration API V2 Child Organisations Webhooks API
  description: 'The Willo Integration API V2 exposes the actions that can be carried out in the Willo asynchronous ("one-way") video interviewing platform as a public REST API, so you can add video interviewing to a job board, ATS, CRM, or staffing platform. Resources include Departments (called "Companies" in the UI), Interviews (the set of pre-defined questions a participant answers - typically a "job" in an ATS), Participants (candidates - no login or app required), their video Responses and identity-verification media, Message Templates (invite/reminder/success email and SMS), Users, Webhooks, Interview Templates, and Child Organisations. Authentication is by API key ("integration key") passed in the Authorization header; each user has their own key from the Willo Integrations page. All requests must be made over HTTPS.

    Endpoint paths, HTTP methods, authentication, status codes, webhook triggers, and the two host environments below are confirmed from Willo''s published Postman API reference. Request and response body schemas are modeled from the documented resource glossary and are illustrative; confirm exact field names and shapes against the live Willo reference before production use.'
  version: '2.0'
  contact:
    name: Willo
    url: https://www.willo.video/api
  termsOfService: https://www.willo.video/terms
servers:
- url: https://api.willotalent.com/api/integrations/v2
  description: Production
- url: https://api.stage.willotalent.com/api/integrations/v2
  description: Staging
security:
- apiKeyAuth: []
tags:
- name: Webhooks
  description: Notifications posted to a third-party endpoint on new response, stage change, new comment, or new score.
paths:
  /webhooks/:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List Webhooks
      description: Lists the configured webhook subscriptions.
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Create Webhook
      description: Subscribes a third-party endpoint to a Willo event trigger - New Response, Stage Change, New Comment, or New Score.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{key}/:
    parameters:
    - $ref: '#/components/parameters/Key'
    put:
      operationId: replaceWebhook
      tags:
      - Webhooks
      summary: Update Webhook (PUT)
      description: Fully replaces a webhook subscription.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWebhook
      tags:
      - Webhooks
      summary: Update Webhook (PATCH)
      description: Partially updates a webhook subscription.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete Webhook
      description: Deletes a webhook subscription.
      responses:
        '204':
          description: The webhook was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    WebhookInput:
      type: object
      required:
      - target_url
      - trigger
      properties:
        target_url:
          type: string
          format: uri
        trigger:
          type: string
          enum:
          - new_response
          - stage_change
          - new_comment
          - new_score
        is_active:
          type: boolean
    Error:
      type: object
      properties:
        detail:
          type: string
    Webhook:
      type: object
      description: A subscription that posts an event payload to a third-party endpoint.
      properties:
        key:
          type: string
        target_url:
          type: string
          format: uri
        trigger:
          type: string
          enum:
          - new_response
          - stage_change
          - new_comment
          - new_score
        is_active:
          type: boolean
  responses:
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was unacceptable, often due to a missing required parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No valid API key was provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Key:
      name: key
      in: path
      required: true
      description: The unique key of the resource.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: The integration key ("API key") available on the Willo Integrations page at https://app.willotalent.com/integrations, sent in the Authorization header. Each user has their own key carrying that user's permissions.