Skip to main content
POST
Create Endpoint

Request Body

string
required
The URL where webhook events will be delivered. Must use HTTPS.
array
required
Array of event types to subscribe to. At least one is required. Available events:
  • call.ended call has ended (always sent)
  • call.transcription_ready transcript is available
  • call.analysis_ready post-call analysis is complete
  • call.recording_ready recording is available
  • call.completed everything is ready (call details, transcript, analysis, recording)
  • call.metrics_ready call metrics are available
Any other value returns 400 with the list of valid event types.
string
Optional human-readable description of the endpoint’s purpose.
array
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.
string
default:"standard"
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

boolean
Indicates if the endpoint was created successfully.
object
The created endpoint, including webhookId (use it for updates and deletion), url, eventTypes, agentIds, isActive and deliveryProfile.
string
The HMAC secret used to verify webhook signatures (64 hexadecimal characters). Store this securely. It is only returned once.
The 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 carries x-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:
For deliveryProfile: "panzo", the signature is the hex HMAC-SHA256 of the raw request body only. Leave out the timestamp:
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.