KaiCalls Webhooks API

openapi: 3.2.0
info:
  title: KaiCalls Public Webhooks API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /v1/webhooks:
    get:
      summary: List webhook subscriptions
      x-required-scopes: webhooks:read
      tags:
      - Webhooks
      operationId: getV1Webhooks
      x-operation-id-source: derived
    post:
      summary: Create or update a webhook subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookUpsert'
      x-required-scopes: webhooks:write
      tags:
      - Webhooks
      operationId: postV1Webhooks
      x-operation-id-source: derived
    patch:
      summary: Update a webhook subscription by id; fields not sent (including URL and events)…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookUpsert'
      x-required-scopes: webhooks:write
      tags:
      - Webhooks
      operationId: patchV1Webhooks
      x-operation-id-source: derived
    delete:
      summary: Delete a webhook subscription
      x-required-scopes: webhooks:write
      tags:
      - Webhooks
      operationId: deleteV1Webhooks
      x-operation-id-source: derived
  /v1/webhooks/test:
    post:
      summary: Send a signed test event to a webhook endpoint (built from the business's most…
      responses:
        '200':
          description: Webhook test delivery result
      x-required-scopes: webhooks:write
      tags:
      - Webhooks
      operationId: postV1WebhooksTest
      x-operation-id-source: derived
  /v1/webhooks/rotate-secret:
    post:
      summary: Rotate a webhook signing secret and return the new secret once
      responses:
        '200':
          description: Rotated webhook secret
      x-required-scopes: webhooks:write
      tags:
      - Webhooks
      operationId: postV1WebhooksRotateSecret
      x-operation-id-source: derived
components:
  schemas:
    webhookUpsert:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: https://www.kaicalls.com/api/v1/schemas/webhookUpsert
      title: Webhook Upsert
      type: object
      additionalProperties: false
      required:
      - business_id
      - webhook_url
      properties:
        id:
          type: string
          format: uuid
        business_id:
          type: string
          format: uuid
        webhook_url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
            - lead.created
            - lead.scored
            - call.received
            - call.started
            - call.completed
            - call.failed
            - call.question_pending
            - sms.received
            - sms.sent
            - sms.delivered
            - sms.failed
            - voicemail.received
            - dispatcher.briefing_created
            - dispatcher.handoff_dispatched
            - phone_number.assigned
            - phone_number.released
            - phone_number.purchased
            - workspace.paused
            - workspace.canceled
            - workspace.created
            - workspace.provisioning_failed
            - workspace.ready
            - workspace.teardown_completed
            - lead_email.sent
            - lead_email.received
            - lead_email.failed
            - callback.scheduled
            - callback.completed
            - conversation.handoff
            - funnel.stage_changed
            - lead_email.delivered
            - lead_email.bounced
            - sms.opted_out
          uniqueItems: true
        description:
          type:
          - string
          - 'null'
        is_active:
          type: boolean
        preset:
          type: string
          enum:
          - generic_crm
          - litify
          - filevine
          - clio_grow
          - lead_docket
          - gohighlevel
          description: Expands to an editable starting-point field map for that CRM. Ignored when payload_template is sent.
        payload_template:
          type:
          - object
          - 'null'
          description: 'Field map { "fields": { "<field>": "<dot path>" | { "value": <constant> } } }. Paths read the standard event body; "a|b" takes the first with a value; a dot in the field name nests it. Missing paths render null. null = standard body.'
          properties:
            fields:
              type: object
              maxProperties: 100
              additionalProperties:
                oneOf:
                - type: string
                - type: object
                  required:
                  - value
                  properties:
                    value:
                      type:
                      - string
                      - number
                      - boolean
                      - 'null'
        custom_headers:
          type:
          - object
          - 'null'
          maxProperties: 20
          additionalProperties:
            type:
            - string
            - 'null'
          description: Extra request headers. A null value keeps the saved value. Content-Type, Host, Content-Length and X-KaiCalls-* are rejected. Values are never returned.
        http_method:
          type: string
          enum:
          - POST
          - PUT
          - PATCH
          default: POST
        body_format:
          type: string
          enum:
          - json
          - form
          default: json
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.