> ## 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.

# Create Endpoint

> Create a webhook endpoint to receive call events.

## Request Body

**url** `string` *required*

The URL where webhook events will be delivered. Must use HTTPS.

**eventTypes** `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.

**description** `string`

Optional human-readable description of the endpoint's purpose.

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

**deliveryProfile** `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](https://stage-docs.oktivo.com/concepts/webhooks.md#panzo-delivery-format) and the [Panzo guide](https://stage-docs.oktivo.com/connectors/panzo.md).

## Response

**success** `boolean`

Indicates if the endpoint was created successfully.

**endpoint** `object`

The created endpoint, including `webhookId` (use it for updates and deletion), `url`, `eventTypes`, `agentIds`, `isActive` and `deliveryProfile`.

**secret** `string`

The HMAC secret used to verify webhook signatures (64 hexadecimal characters). **Store this securely. It is only returned once.**

```json 201 Created theme={null}
{
  "success": true,
  "endpoint": {
    "webhookId": "wh_abc123def456",
    "url": "https://your-app.com/webhooks/oktivo",
    "eventTypes": ["call.ended", "call.analysis_ready", "call.completed"],
    "description": "Panzo results",
    "isActive": true,
    "agentIds": ["agent_sales_qualifier"],
    "payloadMode": "standard",
    "deliveryProfile": "panzo"
  },
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}
```

```json 400 Validation Error theme={null}
{
  "error": "A valid HTTPS URL is required"
}
```

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:

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

// rawBody: the exact bytes received (a Buffer), not JSON.stringify(req.body)
function verifySignature(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);
}
```

For `deliveryProfile: "panzo"`, the signature is the hex HMAC-SHA256 of the raw request body only. Leave out the timestamp:

```javascript theme={null}
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
```

> [!WARNING]
>
> The `secret` is only returned in this response. If you lose it, generate a new one with [Regenerate Secret](https://stage-docs.oktivo.com/api-reference/webhooks/regenerate-secret.md). The old secret stops working immediately.

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


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