> ## Documentation Index
> Fetch the complete documentation index at: https://stage-docs.oktivo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Event-driven notifications for call outcomes and analysis

# 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

| Event | Description |
| - | - |
| `call.ended` | The call has ended. Always sent, even if transcription, recording or analysis fail. Includes status, duration and timestamps |
| `call.transcription_ready` | The transcript is available |
| `call.analysis_ready` | Post-call analysis is complete (includes structured data from the analysis schema) |
| `call.recording_ready` | The recording is uploaded and its link is available |
| `call.completed` | Everything is ready: call details, transcript, analysis and recording. If something is still missing 5 minutes after the call ended, the event is sent anyway with what exists |
| `call.metrics_ready` | Call metrics are available |

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:

```json theme={null}
{
  "id": "evt_abc123",
  "version": "1.0",
  "type": "call.analysis_ready",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "contactUID": "contact_abc123",
    "campaignUID": "campaign_xyz789",
    "phone": "+14155551234",
    "agentId": "agent_def456",
    "orgUID": "org_abc123",
    "analysis_id": "default",
    "analysis": {
      "interested": true,
      "reason": "Wants to upgrade plan",
      "callback_time": "2025-01-16T14:00:00Z"
    },
    "conversation_summary": "Caller wants to upgrade their plan."
  }
}
```

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](https://stage-docs.oktivo.com/guides/webhook-filtering.md) 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:

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(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);
}
```

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](https://stage-docs.oktivo.com/api-reference/webhooks/regenerate-secret.md). The old secret stops working immediately.

> [!NOTE]
>
> 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](https://stage-docs.oktivo.com/connectors/panzo.md).

> [!NOTE]
>
> 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.