InfiVoice Webhooks API

openapi: 3.2.0
info:
  title: InfiVoice REST Webhooks API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Webhooks
  description: 'Webhooks deliver real-time notifications to your server when events occur. Use them to sync data, trigger workflows, or build integrations.


    **Supported Events:**

    - `call.started` — Call initiated

    - `call.completed` — Call ended

    - `call.failed` — Call failed

    - `campaign.started` — Campaign began execution

    - `campaign.completed` — Campaign finished

    - `campaign.paused` — Campaign paused


    **Security:** All webhook payloads include an HMAC-SHA256 signature in the `X-Webhook-Signature` header for verification.'
paths:
  /webhooks:
    get:
      summary: List Webhooks
      description: 'Retrieve all webhook subscriptions. Each webhook listens for specific events and delivers payloads to your endpoint.


        **Webhook Status:**

        - `active` — Receiving events

        - `inactive` — Paused, not receiving events

        - `failed` — Too many delivery failures


        **Required Scope:** `webhooks:read`'
      operationId: listWebhooks
      tags:
      - Webhooks
      responses:
        '200':
          description: List of webhook subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create Webhook
      description: 'Subscribe to events with a new webhook. Your endpoint will receive HTTP POST requests when events occur.


        **Setup Requirements:**

        - HTTPS endpoint (HTTP not allowed for security)

        - Endpoint must respond with 2xx within 30 seconds

        - Failed deliveries are retried with exponential backoff


        **Signature Verification:**

        Each payload includes an `X-Webhook-Signature` header with an HMAC-SHA256 signature. Verify this to ensure authenticity.


        **Required Scope:** `webhooks:write`'
      operationId: createWebhook
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
            examples:
              callEvents:
                summary: Subscribe to call events
                value:
                  url: https://your-server.com/webhooks/infivoice
                  events:
                  - call.started
                  - call.completed
                  - call.failed
              allEvents:
                summary: Subscribe to all events
                value:
                  url: https://your-server.com/webhooks/infivoice
                  events:
                  - call.started
                  - call.completed
                  - call.failed
                  - campaign.started
                  - campaign.completed
      responses:
        '201':
          description: Webhook created with signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/events:
    get:
      summary: List Supported Events
      description: 'Get a list of all event types you can subscribe to. Use these event names when creating webhooks.


        **Event Categories:**

        - `call.*` — Call lifecycle events

        - `campaign.*` — Campaign lifecycle events

        - `contact.*` — Contact changes

        - `subscription.*` — Billing events


        **Required Scope:** `webhooks:read`'
      operationId: listWebhookEvents
      tags:
      - Webhooks
      responses:
        '200':
          description: List of available event types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{id}:
    put:
      summary: Update Webhook
      description: 'Modify a webhook''s configuration. You can change the URL, events, or active status.


        **Tip:** Set `active: false` to temporarily pause a webhook without deleting it.


        **Required Scope:** `webhooks:write`'
      operationId: updateWebhook
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Webhook configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete Webhook
      description: 'Permanently delete a webhook subscription. No further events will be delivered to this endpoint.


        **Required Scope:** `webhooks:write`'
      operationId: deleteWebhook
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Webhook deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks/{id}/test:
    post:
      summary: Test Webhook
      description: 'Send a test payload to verify your webhook endpoint is configured correctly. The test payload mimics a real event.


        **Test Process:**

        1. InfiVoice sends a test payload to your URL

        2. Your server should return 2xx status

        3. Response includes success/failure and timing info


        **Troubleshooting:**

        - Ensure your endpoint is publicly accessible

        - Check that you respond within 30 seconds

        - Verify SSL certificate is valid


        **Required Scope:** `webhooks:write`'
      operationId: testWebhook
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Test results with timing and response info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    WebhookResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          allOf:
          - $ref: '#/components/schemas/Webhook'
          - type: object
            properties:
              secret:
                type: string
                description: Only returned on creation
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    WebhookListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookEventsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            events:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
        meta:
          $ref: '#/components/schemas/Meta'
    UpdateWebhookRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        isActive:
          type: boolean
        description:
          type: string
    DeleteResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            deleted:
              type: boolean
              example: true
        meta:
          $ref: '#/components/schemas/Meta'
    CreateWebhookRequest:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint to receive webhook payloads
        events:
          type: array
          minItems: 1
          items:
            type: string
            enum:
            - call.started
            - call.completed
            - call.failed
            - campaign.started
            - campaign.completed
            - campaign.paused
            - contact.created
            - contact.updated
            - credits.low
            - credits.depleted
        secret:
          type: string
          description: Custom signing secret (auto-generated if not provided)
        description:
          type: string
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookTestResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            delivered:
              type: boolean
            statusCode:
              type: integer
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
        events:
          type: array
          items:
            type: string
        isActive:
          type: boolean
        description:
          type: string
        lastDeliveryAt:
          type: string
          format: date-time
        lastDeliveryStatus:
          type: string
        createdAt:
          type: string
          format: date-time
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      description: Resource UUID
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)