Webhook API Documentation

Overview

The callvine.ai Webhook API allows you to programmatically create call log entries by sending POST requests with call data. This is perfect for integrating with phone systems, CRM platforms, or any application that handles call data.

Important: All webhook requests require API key authentication. Contact your administrator to obtain your API key.

Authentication

Authentication is handled via API keys sent in the request headers. You can include your API key in either of these headers:

X-API-Key: your_api_key_here
Authorization: Bearer your_api_key_here

Security: Never expose your API key in client-side code. Always make webhook calls from your server.

API Endpoint

POST https://callvine.ai/webhook.php

Content-Type: application/json

CORS: Enabled for cross-origin requests

Request Parameters

Parameter	Type	Required	Description	Example
`from_phone`	string	Required	Caller's phone number or identifier	"9087270291"
`to_phone`	string	Required	Called party's phone number or identifier	"8006000009"
`handled_by`	string	Required	Name of the agent who handled the call	"Agent Smith"
`start_time`	string	Required	Call start time in YYYY-MM-DD HH:MM:SS format	"2024-01-15 09:00:00"
`end_time`	string	Required	Call end time in YYYY-MM-DD HH:MM:SS format	"2024-01-15 09:15:00"
`recording_url`	string	Required	URL to the call recording file	"https://example.com/call.wav"
`department`	string	Optional	Department or team that handled the call	"Customer Service"

Request Examples

Choose your preferred programming language to see the implementation example:

curl -X POST https://callvine.ai/webhook.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "from_phone": "9087270291",
    "to_phone": "8006000009",
    "handled_by": "Agent Smith",
    "department": "Customer Service",
    "start_time": "2024-01-15 09:00:00",
    "end_time": "2024-01-15 09:15:00",
    "recording_url": "https://example.com/recordings/call123.wav"
  }'

const response = await fetch('https://callvine.ai/webhook.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    from_phone: '9087270291',
    to_phone: '8006000009',
    handled_by: 'Agent Smith',
    department: 'Customer Service',
    start_time: '2024-01-15 09:00:00',
    end_time: '2024-01-15 09:15:00',
    recording_url: 'https://example.com/recordings/call123.wav'
  })
});

const result = await response.json();
console.log(result);

import requests
import json

url = 'https://callvine.ai/webhook.php'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
}

data = {
    'from_phone': '9087270291',
    'to_phone': '8006000009',
    'handled_by': 'Agent Smith',
    'department': 'Customer Service',
    'start_time': '2024-01-15 09:00:00',
    'end_time': '2024-01-15 09:15:00',
    'recording_url': 'https://example.com/recordings/call123.wav'
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

$url = 'https://callvine.ai/webhook.php';
$data = [
    'from_phone' => '9087270291',
    'to_phone' => '8006000009',
    'handled_by' => 'Agent Smith',
    'department' => 'Customer Service',
    'start_time' => '2024-01-15 09:00:00',
    'end_time' => '2024-01-15 09:15:00',
    'recording_url' => 'https://example.com/recordings/call123.wav'
];

$options = [
    'http' => [
        'header' => [
            'Content-Type: application/json',
            'X-API-Key: your_api_key_here'
        ],
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

Response Examples

The API returns different response formats based on success or failure. Choose a category to see the specific response examples:

Success Response (201 Created)

Upon successful creation, the API returns the complete call log data including the unique ID that can be used for future references or analysis.

{
  "success": true,
  "message": "Call log created successfully",
  "data": {
    "id": 123,
    "from_phone": "9087270291",
    "to_phone": "8006000009",
    "handled_by": "Agent Smith",
    "department": "Customer Service",
    "start_time": "2024-01-15 09:00:00",
    "end_time": "2024-01-15 09:15:00",
    "recording_url": "https://example.com/recordings/call123.wav",
    "title": "Call from 9087270291 to 8006000009 (handled by Agent Smith)",
    "created_at": "2024-01-15 10:30:00"
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Always true for successful requests
`message`	string	Human-readable success message
`data.id`	integer	Unique identifier of the created call log (use for analysis: recording.php?call_id=123)
`data.*`	various	Echo of the submitted call data plus generated fields

Client Error Responses (4xx)

These errors indicate issues with the request data or authentication:

Missing Required Fields (400)

{
  "error": "Missing required fields",
  "message": "The following fields are required: from_phone, handled_by, recording_url",
  "missing_fields": ["from_phone", "handled_by", "recording_url"]
}

Invalid DateTime Format (400)

{
  "error": "Invalid start_time format",
  "message": "start_time must be in YYYY-MM-DD HH:MM:SS format",
  "example": "2024-01-15 09:00:00"
}

Invalid Time Range (400)

{
  "error": "Invalid time range",
  "message": "end_time must be after start_time"
}

Invalid Recording URL (400)

{
  "error": "Invalid recording URL",
  "message": "recording_url must be a valid URL"
}

Invalid JSON (400)

{
  "error": "Invalid JSON",
  "message": "Request body must be valid JSON"
}

Authentication Required (401)

{
  "error": "Authentication required",
  "message": "API key must be provided in X-API-Key header or Authorization header"
}

Invalid API Key (401)

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

Method Not Allowed (405)

{
  "error": "Method not allowed",
  "message": "This endpoint only accepts POST requests",
  "allowed_methods": ["POST"]
}

Server Error Responses (5xx)

These errors indicate issues on the server side:

Database Error (500)

{
  "error": "Database error",
  "message": "Failed to insert call log into database"
}

Internal Server Error (500)

{
  "error": "Internal server error",
  "message": "An unexpected error occurred while processing the request"
}

HTTP Status Codes

201 Created

Call log was successfully created

400 Bad Request

Invalid request data or missing required fields

401 Unauthorized

Missing or invalid API key

405 Method Not Allowed

Only POST requests are accepted

500 Internal Server Error

Server error occurred while processing request

For detailed JSON response examples, see the Response Examples section above which contains organized tabs for success and error responses.

Testing Your Integration

For testing purposes, you can use these test API keys:

Test API Key: test_key_123
Production API Key: prod_key_456

Note: Contact your administrator to get your actual production API keys. Test keys are for development only.

Validation Checklist

✓ API key is included in request headers
✓ Content-Type is set to application/json
✓ All required fields are present and non-empty
✓ DateTime fields are in YYYY-MM-DD HH:MM:SS format
✓ end_time is after start_time
✓ recording_url is a valid URL (required)
✓ Handle both success and error responses

Need Help?

If you have questions about the webhook API or need assistance with integration, please contact our support team or check the main dashboard for additional resources.

Go to Dashboard