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.

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",
      "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

​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

​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

Next Steps