Documentation

Inbound Call Webhook

Webhook endpoint that routes inbound calls to a specific agent

Inbound Run Webhook#

Webhook endpoint that starts agent runs from inbound calls

Configure this URL in your telephony provider's dashboard (Twilio, Vonage, etc.) to start agent runs from inbound calls to a specific agent. The workflow_id determines which agent handles the call.

See Inbound calls for full setup instructions per provider.

Quick reference#

Webhook endpoint that routes inbound calls to a specific agent. Send the request to POST /api/v1/telephony/inbound/{workflowid} on the Paladin API base URL.

Method	`POST`
Path	`/api/v1/telephony/inbound/{workflowid}`
Path parameters	workflowid
Authentication	Use the authentication method shown in the OpenAPI block and the Authentication docs. Keep API keys server-side.

Before you call#

Confirm you are using the production base URL shown in the API reference.
Make sure any path IDs belong to the same Paladin organization as the credential you are using.
Validate request bodies and required fields before sending production traffic.

Common error checks#

Use 401 or 403 responses to check credentials, organization scope, and permissions.
Use 404 responses to check whether the referenced resource exists in the current organization.
Use 422 responses to inspect missing or invalid request fields.

OpenAPI#

POST /api/v1/telephony/inbound/{workflowid}

openapi: 3.1.0
info:
  title: Paladin API
  description: API for the Paladin app
  version: 1.0.0
servers:
  - url: https://app.paladin.northmanngrp.com
    description: Production

security: []
paths:
  /api/v1/telephony/inbound/{workflow_id}:
    post:
      tags:
        - main
      summary: Handle Inbound Telephony
      description: |-
        [LEGACY] Per-workflow inbound webhook.

        Superseded by ``POST /inbound/run``, which resolves the workflow from
        the called number's ``inbound_workflow_id`` and lets a single webhook
        URL serve every workflow in the org. New integrations should point
        their provider at ``/inbound/run``; this route is kept only for
        existing provider configurations that still encode ``workflow_id``
        in the URL.
      operationId: handle_inbound_telephony_api_v1_telephony_inbound__workflow_id__post
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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