Skip to main content

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

  1. Register a webhook endpoint with a URL and the event types you want
  2. When a matching event occurs, Oktivo sends a POST request to your URL
  3. Your server processes the payload and returns a 200 response
  4. If delivery fails, Oktivo retries with exponential backoff

Payload Structure

Every webhook payload includes:
The 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 set agentIds (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
See the Webhook Filtering Guide for details.

HMAC Signature Verification

Every standard webhook request includes x-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:
The 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 set deliveryProfile: "panzo". The default is "standard", and panzo is not available in custom payload mode. With this format:
  • X-Oktivo-Signature is the hex HMAC-SHA256 of the raw request body only, with no timestamp in the signed input. The X-Oktivo-Timestamp header is still sent but is not signed.
  • The payload also carries a top-level event field (same as type), data.summary and data.transcript (a list of { role, text } turns).
For the full setup, see the Panzo guide.
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 2xx response 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 200 immediately, then process asynchronously
  • Use idempotency keys (the contactUID + event type) to handle duplicate deliveries
  • Set up agent filtering to keep webhook handlers focused