Webhooks
Webhooks deliver real-time notifications to your application when events occur in Oktivo. Instead of polling for results, your server receives a POST request as soon as something happens.Event Types
There is no separate failure event. A call that was not answered arrives as
call.ended with a callStatus such as not picked, not_answered or rejected.
How It Works
- Register a webhook endpoint with a URL and the event types you want
- When a matching event occurs, Oktivo sends a POST request to your URL
- Your server processes the payload and returns a
200response - If delivery fails, Oktivo retries with exponential backoff
Payload Structure
Every webhook payload includes:data object depends on the event. call.ended carries callStatus, callDuration, billingDuration, disconnectReason, timestamps, attempts, transcriptionStatus and analysisStatus. call.analysis_ready carries analysis_id, analysis and conversation_summary. call.completed carries all of these, plus transcription and recordingUrl. Every event also has contactUID, phone, campaignUID, agentId and orgUID, and includes dynamicVariables when the call had any.
Agent Filtering
You can scope a webhook endpoint to only receive events from specific agents. In the dashboard use Agent Filter on the Endpoint step. Through the API setagentIds (up to 50 agents) when creating the endpoint. This is useful when:
- Different CRMs handle different agents
- You want to route events to different processing pipelines
- Multiple teams share an Oktivo account
HMAC Signature Verification
Every standard webhook request includesx-oktivo-signature and x-oktivo-timestamp headers. The signature is the hex HMAC-SHA256 of timestamp + "." + raw body, keyed with your endpoint secret. Oktivo never sends an unsigned standard delivery. Verify against the raw request body, not a re-serialized JSON object:
secret is returned when you create the webhook endpoint. Store it securely. If you lose it, use Regenerate Secret on the endpoint’s Review step in Connecter > Webhooks, or call Regenerate Secret. The old secret stops working immediately.
The Send Test button in the webhook wizard sends a sample request without a signature (it runs before the secret exists) and marks it with the header
X-Oktivo-Test-Delivery: true. A receiver that requires a valid signature will reject it. Use a real call to test signature checks.Panzo Delivery Format
Standard endpoints can opt in to a Panzo-compatible format. In the dashboard, set Delivery format to Panzo CRM (Standard payload mode only). Through the API setdeliveryProfile: "panzo". The default is "standard", and panzo is not available in custom payload mode. With this format:
X-Oktivo-Signatureis the hex HMAC-SHA256 of the raw request body only, with no timestamp in the signed input. TheX-Oktivo-Timestampheader is still sent but is not signed.- The payload also carries a top-level
eventfield (same astype),data.summaryanddata.transcript(a list of{ role, text }turns).
The
recordingUrl in payloads is a presigned link that expires after 7 days. Download the recording promptly if you need to keep it.Delivery & Retries
- Oktivo expects a
2xxresponse within 10 seconds - Failed deliveries are retried up to 8 times after the first attempt, at 10s, 30s, 1m, 5m, 15m, 30m, 1h and 2h
- An endpoint is automatically disabled after 50 consecutive failed deliveries
- You can view delivery logs in the dashboard
Best Practices
- Always verify the HMAC signature before processing
- Return
200immediately, then process asynchronously - Use idempotency keys (the
contactUID+ event type) to handle duplicate deliveries - Set up agent filtering to keep webhook handlers focused