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>",
"agentId": "<string>"
}
'import requests
url = "https://client-backend.oktivo.com/webhooks/endpoints"
payload = {
"url": "<string>",
"eventTypes": [{}],
"description": "<string>",
"agentId": "<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>',
agentId: '<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>',
'agentId' => '<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 \"agentId\": \"<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 \"agentId\": \"<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 \"agentId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"webhookId": "wh_abc123def456",
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
{
"success": false,
"message": "url must use HTTPS"
}
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>",
"agentId": "<string>"
}
'import requests
url = "https://client-backend.oktivo.com/webhooks/endpoints"
payload = {
"url": "<string>",
"eventTypes": [{}],
"description": "<string>",
"agentId": "<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>',
agentId: '<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>',
'agentId' => '<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 \"agentId\": \"<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 \"agentId\": \"<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 \"agentId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"webhookId": "wh_abc123def456",
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
{
"success": false,
"message": "url must use HTTPS"
}
Request Body
string
required
The URL where webhook events will be delivered. Must use HTTPS.
array
required
Array of event types to subscribe to. Available events:
call.endedcall has endedcall.analysis_readypost-call analysis is completecall.completedcontact reached terminal statecall.faileda call attempt failed
string
Optional human-readable description of the endpoint’s purpose.
string
Optional filter events to only those from a specific agent. If omitted, the endpoint receives events from all agents. See Webhook Filtering.
Response
boolean
Indicates if the endpoint was created successfully.
string
Unique identifier for the webhook endpoint. Use this for updates and deletion.
string
The HMAC secret used to verify webhook signatures. Store this securely it is only returned once.
{
"success": true,
"webhookId": "wh_abc123def456",
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
{
"success": false,
"message": "url must use HTTPS"
}
Verifying Webhook Signatures
Use the returnedsecret to verify the x-oktivo-signature header on incoming webhooks:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
The
secret is only returned in this response. If you lose it, you’ll need to delete and recreate the endpoint.This endpoint requires JWT authentication.