Create Endpoint
curl --request POST \
--url https://client-backend.oktivo.com/webhooks/endpoints \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"eventTypes": [
{}
],
"description": "<string>",
"agentIds": [
{}
],
"deliveryProfile": "<string>"
}
'import requests
url = "https://client-backend.oktivo.com/webhooks/endpoints"
payload = {
"url": "<string>",
"eventTypes": [{}],
"description": "<string>",
"agentIds": [{}],
"deliveryProfile": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
eventTypes: [{}],
description: '<string>',
agentIds: [{}],
deliveryProfile: '<string>'
})
};
fetch('https://client-backend.oktivo.com/webhooks/endpoints', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-backend.oktivo.com/webhooks/endpoints",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'eventTypes' => [
[
]
],
'description' => '<string>',
'agentIds' => [
[
]
],
'deliveryProfile' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-backend.oktivo.com/webhooks/endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-backend.oktivo.com/webhooks/endpoints")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-backend.oktivo.com/webhooks/endpoints")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"endpoint": {
"webhookId": "wh_abc123def456",
"url": "https://your-app.com/webhooks/oktivo",
"eventTypes": ["call.ended", "call.analysis_ready", "call.completed"],
"description": "Panzo results",
"isActive": true,
"agentIds": ["agent_sales_qualifier"],
"payloadMode": "standard",
"deliveryProfile": "panzo"
},
"secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
{
"error": "A valid HTTPS URL is required"
}
Webhooks
Create Endpoint
Create a webhook endpoint to receive call events.
POST
/
webhooks
/
endpoints
Create Endpoint
curl --request POST \
--url https://client-backend.oktivo.com/webhooks/endpoints \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"eventTypes": [
{}
],
"description": "<string>",
"agentIds": [
{}
],
"deliveryProfile": "<string>"
}
'import requests
url = "https://client-backend.oktivo.com/webhooks/endpoints"
payload = {
"url": "<string>",
"eventTypes": [{}],
"description": "<string>",
"agentIds": [{}],
"deliveryProfile": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
eventTypes: [{}],
description: '<string>',
agentIds: [{}],
deliveryProfile: '<string>'
})
};
fetch('https://client-backend.oktivo.com/webhooks/endpoints', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-backend.oktivo.com/webhooks/endpoints",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'eventTypes' => [
[
]
],
'description' => '<string>',
'agentIds' => [
[
]
],
'deliveryProfile' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-backend.oktivo.com/webhooks/endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-backend.oktivo.com/webhooks/endpoints")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-backend.oktivo.com/webhooks/endpoints")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"eventTypes\": [\n {}\n ],\n \"description\": \"<string>\",\n \"agentIds\": [\n {}\n ],\n \"deliveryProfile\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"endpoint": {
"webhookId": "wh_abc123def456",
"url": "https://your-app.com/webhooks/oktivo",
"eventTypes": ["call.ended", "call.analysis_ready", "call.completed"],
"description": "Panzo results",
"isActive": true,
"agentIds": ["agent_sales_qualifier"],
"payloadMode": "standard",
"deliveryProfile": "panzo"
},
"secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
{
"error": "A valid HTTPS URL is required"
}
Request Body
Array of event types to subscribe to. At least one is required. Available events:
call.endedcall has ended (always sent)call.transcription_readytranscript is availablecall.analysis_readypost-call analysis is completecall.recording_readyrecording is availablecall.completedeverything is ready (call details, transcript, analysis, recording)call.metrics_readycall metrics are available
400 with the list of valid event types.Optional list of agent IDs (up to 50). The endpoint then receives events only from those agents. If omitted or empty, it receives events from all agents. Every ID must belong to your account. The older single
agentId string is still accepted. See Webhook Filtering.Optional delivery format.
standard (default) sends the normal signed payload. panzo sends a Panzo-compatible variant (signature over the raw body only, plus event, data.summary and data.transcript). Only valid with the standard payload mode; with custom mode the request returns 400. See Webhooks and the Panzo guide.Response
The created endpoint, including
webhookId (use it for updates and deletion), url, eventTypes, agentIds, isActive and deliveryProfile.The HMAC secret used to verify webhook signatures (64 hexadecimal characters). Store this securely. It is only returned once.
{
"success": true,
"endpoint": {
"webhookId": "wh_abc123def456",
"url": "https://your-app.com/webhooks/oktivo",
"eventTypes": ["call.ended", "call.analysis_ready", "call.completed"],
"description": "Panzo results",
"isActive": true,
"agentIds": ["agent_sales_qualifier"],
"payloadMode": "standard",
"deliveryProfile": "panzo"
},
"secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
{
"error": "A valid HTTPS URL is required"
}
endpoint object in the real response also contains the custom-mode fields (method, headers, bodyType, bodyTemplate, auth, conditions, timeoutMs, retryOnFailure, maxRetries), which are not used in standard mode.
Verifying Webhook Signatures
Each delivery carriesx-oktivo-signature and x-oktivo-timestamp headers. For the standard delivery format, the signature is the hex HMAC-SHA256, keyed with the returned secret, of the timestamp, a ., and the raw request body exactly as received:
const crypto = require('crypto');
// rawBody: the exact bytes received (a Buffer), not JSON.stringify(req.body)
function verifySignature(rawBody, signature, timestamp, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest('hex');
const a = Buffer.from(signature || '');
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
deliveryProfile: "panzo", the signature is the hex HMAC-SHA256 of the raw request body only. Leave out the timestamp:
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
The
secret is only returned in this response. If you lose it, generate a new one with Regenerate Secret. The old secret stops working immediately.This endpoint requires JWT authentication (the login token of a dashboard user), not an
okt_ API token. Your plan must include the Webhooks feature. An account can have up to 50 endpoints; more returns 409.