Custom Integration

Overview

The custom integration feature allows you to send call transcripts from your own backend system or third-party service to Cekura via webhooks. This provides flexibility to integrate any voice platform while maintaining full control over your conversation data.

How It Works

Configure your agent in Cekura and select “Custom” as the provider
Cekura provides you with a webhook URL
After each call ends, send the call data to the webhook URL
Cekura listens for call data for 5 minutes after the call ends
View evaluation results in the Cekura dashboard

Setup

In Cekura Dashboard

Create or edit an agent in the Cekura dashboard
Set the transcript provider to “Custom”
Copy the webhook URL provided by Cekura
Note your API key for authentication

One webhook URL per project: Cekura provides a single webhook URL per project. If you need separate webhook destinations for different environments (e.g., development vs. production), create separate projects in Cekura — each project gets its own webhook URL and API key. This is the recommended approach for environment isolation.

Webhook Implementation Requirements

Your system should send call transcripts to the Cekura webhook with the following specifications: HTTP Method: POST Headers:

X-CEKURA-API-KEY: your-api-key-here
Content-Type: application/json

Timing: Send the call data within 5 minutes after the call ends. Cekura will listen for webhooks for 5 minutes after the call ends.

Payload Format

Your webhook POST request should send a JSON payload with the following structure:

Top Level Structure

{
  "agent_id": 123,  // Conditionally required: The ID of the AI agent in Cekura (see note below)
  "calls": [...]    // Required: Array of call objects
}

agent_id is required unless every call object in calls includes a run_id field. If you already have a Cekura Run ID for each call before sending the webhook — for example, when using SIP integrations where run IDs are available from SIP headers — you can omit agent_id entirely and include run_id on each call object instead. In this case, Cekura will trust the provided run IDs and match transcripts directly to the existing runs.

Call Object Structure

Each call in the calls array should include:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for this call from your system (max 255 chars)
`startedAt`	string	Yes	Call start time in ISO 8601 format
`endedAt`	string	Yes	Call end time in ISO 8601 format
`messages`	array	No	List of transcript messages (see below)
`to_phone_number`	string	No	Phone number that received the call (must start with + followed by digits, max 15 chars). Example: ‘+14155551234’
`from_phone_number`	string	No	Phone number that initiated the call (must start with + followed by digits, max 15 chars). Example: ‘+18005551234’
`metadata`	object	No	Optional metadata as key-value pairs for additional call information
`endedReason`	string	No	Reason call ended (default: “unknown”, e.g., “assistant-ended-call”, “customer-hungup”)
`run_id`	string	Conditionally required	Cekura Run ID for this call. Required on each call when `agent_id` is omitted at the top level. Intended for SIP integrations where run IDs are pre-known from SIP headers.
`trace_id`	string	No	OpenTelemetry trace ID for this call (max 32 chars). When provided, it is attached to the matched run so the OTel trace links to the call in the Cekura dashboard. See Tracing.

Passing a recording URL: The custom integration payload does not have a dedicated voice_recording_url field. To include a recording URL (or any other custom call context), add it to the metadata object:

"metadata": {
  "recording_url": "https://recordings.example.com/call_123.wav"
}

You can then reference it in metrics:

LLM Judge metrics: use {{metadata.recording_url}} in your metric description
Python metrics: use data["metadata"]["recording_url"]

See Metric Variables for the full reference of variables available in metrics.

Message Object Structure

Each message in the messages array should include:

Field	Type	Required	Description
`role`	string	Yes	Message role: “bot”, “user”, “system”, “function_call”, or “function_call_result”
`content`	string	Yes	The message content or function description
`start_time`	number	No	Start time in milliseconds from epoch
`end_time`	number	No	End time in milliseconds from epoch
`data`	object	No	Additional data for function calls

For function call messages, use the data field to include the tool call details. See the Transcript Format page for examples of how to structure function_call and function_call_result messages in Cekura format.

Complete Example

Here’s a complete example payload with two calls:

{
  "agent_id": 2,
  "calls": [
    {
      "id": "0199e72d-795e-7ffe-b9b9-d3b08a3a11ae",
      "startedAt": "2025-10-15T09:22:21.787Z",
      "endedAt": "2025-10-15T09:24:30.229Z",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "to_phone_number": "+18646190758",
      "from_phone_number": "+14155551234",
      "messages": [
        {
          "role": "bot",
          "content": "Hi there. This is Alex from Tech Solutions customer support. How can I help you today?",
          "start_time": 1760520142852,
          "end_time": 1760520147842
        },
        {
          "role": "user",
          "content": "Yeah. I have a question about a recent recurring charge on my account.",
          "start_time": 1760520149392,
          "end_time": 1760520153012
        },
        {
          "role": "bot",
          "content": "Got it. Let me help you figure that out. Could you tell me the email address linked to your account so I can look this up for you?",
          "start_time": 1760520154442,
          "end_time": 1760520160522
        },
        {
          "role": "user",
          "content": "Okay. It's john dot doe at email dot com",
          "start_time": 1760520157372,
          "end_time": 1760520165132
        }
      ],
      "metadata": {
        "customer_name": "John Doe",
        "call_type": "support"
      },
      "endedReason": "customer-hungup"
    },
    {
      "id": "0199e72d-791d-7eee-b5d9-b82843919e42",
      "startedAt": "2025-10-15T09:22:21.727Z",
      "endedAt": "2025-10-15T09:23:48.100Z",
      "to_phone_number": "+18646190758",
      "from_phone_number": "+14155559999",
      "messages": [
        {
          "role": "bot",
          "content": "Hi there. This is Alex from Tech Solutions customer support. How can I help you today?",
          "start_time": 1760520142868,
          "end_time": 1760520147998
        },
        {
          "role": "user",
          "content": "Yeah. The Taskmaster Pro app keeps crashing.",
          "start_time": 1760520149538,
          "end_time": 1760520152118
        }
      ],
      "metadata": {
        "customer_name": "Jane Smith",
        "call_type": "technical_issue"
      },
      "endedReason": "assistant-ended-call"
    }
  ]
}

SIP / Pre-known Run ID Example

If you are using a SIP integration and already have Cekura Run IDs available from SIP headers before sending the webhook, you can omit agent_id at the top level and include run_id on each call instead. Cekura will trust the provided run IDs and attach the transcripts directly to the matching runs — no agent lookup needed.

{
  "calls": [
    {
      "id": "sip-call-abc123",
      "run_id": "456789",
      "startedAt": "2025-10-15T09:22:21.787Z",
      "endedAt": "2025-10-15T09:24:30.229Z",
      "to_phone_number": "+18646190758",
      "from_phone_number": "+14155551234",
      "messages": [
        {
          "role": "bot",
          "content": "Hi there. How can I help you today?"
        },
        {
          "role": "user",
          "content": "I have a billing question."
        }
      ],
      "endedReason": "customer-hungup"
    }
  ]
}

When using run_id per call, every call in the calls array must include a run_id. Mixing calls with and without run_id in the same payload (when agent_id is absent) is not supported.

Important Considerations

For successful webhook integration, ensure:

Timing: Send the call data within 5 minutes after the call ends
Authentication: Include the X-CEKURA-API-KEY header with your API key
Phone Numbers: Phone numbers must start with + followed by digits (max 15 chars, e.g., ‘+14155551234’). The to_phone_number should match the scenario’s inbound number for testing
Timestamps: Use ISO 8601 format for startedAt and endedAt
Message Timing: Use milliseconds from epoch for message start_time and end_time (optional fields)
Agent ID: Use the correct agent ID from your Cekura dashboard. If you have a Cekura Run ID available ahead of time (e.g. from SIP headers), you can omit agent_id and include run_id on each call object instead — Cekura will match transcripts directly to the existing runs
Unique Call IDs: Each call should have a unique identifier (max 255 chars)
Metadata: Use the metadata field to pass additional key-value pairs for call information

Troubleshooting

If your webhook integration isn’t working as expected:

No calls appear in Cekura

Verify the webhook URL is correct
Check that the X-CEKURA-API-KEY header is included and correct
Ensure the payload format matches the specification
Confirm the agent_id is correct
Verify the call data was sent within 5 minutes after the call ended

Authentication issues

Double-check your API key is correct
Ensure the header name is exactly X-CEKURA-API-KEY (case-sensitive)
Verify the API key has proper permissions

Calls not matching scenarios

Confirm the to_phone_number in the payload matches the scenario’s inbound number
Ensure phone numbers start with + followed by digits (max 15 chars)
Check that the call ID is unique and under 255 characters
Verify timestamps are in ISO 8601 format

Invalid payload errors

Validate your JSON payload structure
Ensure all required fields are present (id, startedAt, endedAt)
Verify the agent_id is an integer, not a string (required unless each call includes a run_id)
Check that phone numbers follow the correct format (+ followed by digits, max 15 chars)
Ensure messages is an array with dictionaries containing role and content fields

Mock Tools (optional)

If your agent calls tools and you want to test it without hitting live third-party services, use Mock Tools. There are two ways to wire mocking into a custom / self-hosted integration:

MCP auto-discovery (recommended if your agent uses an MCP server). Cekura reads your tool list directly from your own MCP server, generates mock data, and then hosts a drop-in mock MCP endpoint you point your agent at during test runs. No per-tool wiring. Covered in Mock an MCP server.
Per-tool webhooks (works for any agent). Point each tool at its individual Cekura mock endpoint. Covered in Per-tool webhook mocking.

Whichever you use, you must also report each tool call in your transcript — otherwise tool-based metrics have nothing to score against.

Mock an MCP server

If your self-hosted agent talks to an MCP server (JSON-RPC 2.0) for its tools, Cekura can discover those tools automatically and stand in for the server during tests. You never rewrite individual tool URLs — you swap one MCP endpoint. Prerequisite: your agent’s MCP server must be reachable by Cekura and expose the standard tools/list method. Provide any auth as headers; they are stored encrypted.

Auto-fetch tools from your MCP server

Call auto-fetch with provider="custom" and your MCP server URL. Cekura queries tools/list, LLM-generates realistic mock input/output data for each tool from your agent’s context, and registers them all under a single Cekura-hosted mock MCP endpoint.

curl -X POST https://api.cekura.ai/test_framework/v1/aiagents/{agent_id}/tools/auto-fetch/ \
  -H "X-CEKURA-API-KEY: $CEKURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "custom",
    "mcp_server_url": "https://your-agent.example.com/mcp",
    "mcp_server_headers": {"Authorization": "Bearer <token>"}
  }'

Returns a progress_id. Poll GET .../tools/auto-fetch-progress/?progress_id=<id> until status is completed. That’s the only setup call — there is no separate “enable” step for a self-hosted agent.

The mcp_server_url is validated before any request is made: only http/https schemes are allowed, private / loopback / link-local / cloud-metadata addresses are blocked (DNS is resolved and checked), and headers that could rewrite the request (Host, Cookie, X-Forwarded-*) are rejected. Headers are stored encrypted. An agent is pinned to a single MCP server — re-running auto-fetch with the same URL refreshes the tools; switching to a different URL requires deleting the existing mock tools first.

Review and edit the generated mock data

List the tools with GET .../tools/ and refine any input/output mappings (PATCH the mock tool). Add one entry per input variation your evaluators exercise — see Handling Dynamic Input Parameters. Re-running auto-fetch preserves tools that already have mock data.

Get your mock MCP endpoint URL

Read GET .../tools/mock-status/ — it returns the stable Cekura-hosted MCP endpoint for your agent under mcp_endpoints[]:

{
  "mock_enabled": true,
  "provider": "custom",
  "mcp_endpoints": [
    {
      "mock_index": 1,
      "url": "https://api.cekura.ai/test_framework/v1/aiagents/{agent_id}/mcp/1/",
      "tool_names": ["get_account", "book_appointment"]
    }
  ],
  "tool_endpoints": []
}

Always read the URL from the API — don’t hand-build it, so it stays correct across environments.

Point your agent at the mock endpoint during test runs

Configure your agent’s MCP client to use mcp_endpoints[0].url instead of your real MCP server for the duration of a test. It is a standard MCP JSON-RPC 2.0 server (initialize, tools/list, tools/call) and requires no authentication. A tools/call returns your configured mock output:

// Request  POST .../mcp/1/
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "get_account", "arguments": {"user_id": 1}}}

// Response
{"jsonrpc": "2.0", "id": 1,
 "result": {"content": [{"type": "text", "text": "{\"account_tier\": \"Premium\"}"}]}}

Enabling and disabling mocking is entirely on your side: point the MCP client at this URL to use the mocks, or back at your real server to stop. Cekura can’t reach into a self-hosted agent to flip it for you.

The mock MCP endpoint makes your tools respond correctly, but the Mock Tool Call Accuracy metric scores the transcript, not the endpoint. You must still emit a function_call message per tool call in the transcript you post — see Report the tool call in your transcript below.

Per-tool webhook mocking

If your agent does not use MCP, mock each tool individually. There are two pieces — both required for tool-based evaluation to work. 1. Call the Cekura mock endpoint during the call. Point the tool at its Cekura mock endpoint instead of the real service. During the call, your agent makes a normal HTTP request and gets back the mock output you configured.

Method: POST
Body: the tool’s arguments as a flat JSON object — the same shape as the input in your mock configuration. For example, a tool whose mock entry is {"input": {"user_id": 1}, ...} is called with body {"user_id": 1}.
Authentication: include your X-CEKURA-API-KEY header. A missing or wrong key is the most common cause of a mock call failing.
The endpoint matches your request against the configured input/output mappings and returns the matching output.

See the Mock Tool API reference for the exact endpoint and request/response schema.

Report the tool call in your transcript

Calling the mock endpoint makes the tool respond correctly during the call, but it does not by itself tell Cekura’s metrics that a tool was used. The Mock Tool Call Accuracy metric (and any tool-based metric) reads the transcript to determine what was called. So your webhook messages array must include a function_call message for each tool call, carrying the tool name and arguments in its data object:

{
  "role": "function_call",
  "content": "",
  "data": {
    "id": "call_abc",
    "name": "pre_call_lookup",
    "arguments": {}
  }
}

Include the paired result as well (recommended):

{
  "role": "function_call_result",
  "content": "",
  "data": {
    "id": "call_abc",
    "name": "pre_call_lookup",
    "result": { "account_id": "TEST-90210", "account_tier": "Premium" }
  }
}

If you omit these function_call messages, the Mock Tool Call Accuracy metric will report the tool as not called and the result will fail — even when the tool was actually called and used correctly during the call. The mock endpoint being hit is not visible to the metric; only the transcript is.

A tool that takes no input must still send "arguments": {}. See Transcript Format for a complete transcript example with function calls.

Get Started

Key Concepts

Guides

Integrations

Advanced

Custom Integration

Overview

How It Works

Setup

In Cekura Dashboard

Webhook Implementation Requirements

Payload Format

Top Level Structure

Call Object Structure

Message Object Structure

Complete Example

SIP / Pre-known Run ID Example

Important Considerations

Troubleshooting

No calls appear in Cekura

Authentication issues

Calls not matching scenarios

Invalid payload errors

Mock Tools (optional)

Mock an MCP server

Per-tool webhook mocking

Report the tool call in your transcript

Next Steps

​Overview

​How It Works

​Setup

​In Cekura Dashboard

​Webhook Implementation Requirements

​Payload Format

​Top Level Structure

​Call Object Structure

​Message Object Structure

​Complete Example

​SIP / Pre-known Run ID Example

​Important Considerations

​Troubleshooting

​No calls appear in Cekura

​Authentication issues

​Calls not matching scenarios

​Invalid payload errors

​Mock Tools (optional)

​Mock an MCP server

​Per-tool webhook mocking

​Report the tool call in your transcript

​Next Steps

Overview

How It Works

Setup

In Cekura Dashboard

Webhook Implementation Requirements

Payload Format

Top Level Structure

Call Object Structure

Message Object Structure

Complete Example

SIP / Pre-known Run ID Example

Important Considerations

Troubleshooting

No calls appear in Cekura

Authentication issues

Calls not matching scenarios

Invalid payload errors

Mock Tools (optional)

Mock an MCP server

Per-tool webhook mocking

Report the tool call in your transcript

Next Steps