Custom Integration

Learn how to send call transcripts from your own backend system to Cekura using webhooks for simulation testing and observability.

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

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

Setup

In Cekura Dashboard

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

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: ‘[phone]’
from_phone_number	string	No	Phone number that initiated the call (must start with + followed by digits, max 15 chars). Example: ‘[phone]’
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.

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": "[phone]",
      "from_phone_number": "[phone]",
      "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": "[phone]",
      "from_phone_number": "[phone]",
      "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": "[phone]",
      "from_phone_number": "[phone]",
      "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:

1. Timing: Send the call data within 5 minutes after the call ends
2. Authentication: Include the X-CEKURA-API-KEY header with your API key
3. Phone Numbers: Phone numbers must start with + followed by digits (max 15 chars, e.g., ‘[phone]’). The to_phone_number should match the scenario’s inbound number for testing
4. Timestamps: Use ISO 8601 format for startedAt and endedAt
5. Message Timing: Use milliseconds from epoch for message start_time and end_time (optional fields)
6. 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
7. Unique Call IDs: Each call should have a unique identifier (max 255 chars)
8. 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

Next Steps

• Learn about custom metrics
• Explore predefined metrics
• Set up instruction following metric