Webhook Overview

Webhooks deliver an AI-generated summary of each completed call — including the full conversation transcript, tags, interest classification, and any custom keys extracted by the AI — to an endpoint you control. Use them to push call outcomes into your CRM, analytics pipeline, or internal tooling.

Webhooks setup

To set up webhooks, go to Settings > Webhooks in the Dashboard and add the URLs you would like to receive events on. A company can configure multiple active webhook URLs; leaving the list empty disables delivery. When a webhook is created, a signing secret is automatically generated. Every dispatch is signed with HMAC-SHA256 using that secret — you can verify the signature on your server to confirm the request originated from Olimi and that the payload wasn’t tampered with.

When a webhook fires

A webhook is sent once per call, after the AI summary pipeline finishes for that call. Specifically:

The call must have a transcript with at least one user message (calls with no user messages are summarized as “No message was left during this call.”).
The company must have at least one active webhook configured.
Delivery is asynchronous and queued — the webhook is dispatched after the call record is committed to the database.

If a receiver returns a non-2xx response, the job is retried according to the standard queue retry policy. Failures are logged but do not roll back the underlying call record.

Request format


Method	`POST`
Content-Type	`application/json`
`X-Olimi-Timestamp`	Unix timestamp (seconds) of when the request was sent — present when a signing secret is configured
`X-Olimi-Signature`	`sha256=<hmac_hex>` — HMAC-SHA256 signature of the request — present when a signing secret is configured
Body	A single flat JSON object (see below)

The body is a plain JSON object — not a JSON:API envelope. Treat unknown fields as additive; new fields may be introduced without a breaking change.

Signing secret

Each webhook has a whsec_ signing secret (48 hex characters). The full secret is shown only on create or rotate — copy it immediately. All other API responses return a masked hint (whsec_…XXXX). From Settings > Webhooks use the rotate (↻) and revoke (🗑) icons to manage the secret, or via the API:

POST /api/v2/organization-webhooks/:id/rotate-token — generates a new secret; old one is immediately invalidated
DELETE /api/v2/organization-webhooks/:id/token — clears the secret; dispatches will send no signature headers until rotated

Signature verification

When a webhook has a signing secret configured, every outbound request includes two headers:

X-Olimi-Timestamp — the Unix timestamp (seconds) at the time of dispatch
X-Olimi-Signature — sha256= followed by the lowercase hex HMAC-SHA256 digest

How the signature is constructed

The signed message is formed by concatenating the timestamp, a dot, and the raw JSON body:

signed_message = timestamp + "." + raw_body
signature      = "sha256=" + HMAC-SHA256(signing_secret, signed_message)

Including the timestamp in the signed message ties the signature to a specific point in time, so a captured request cannot be replayed later with a valid signature.

Why HMAC over a Bearer token

With a raw Bearer token, your server compares the incoming header value to a stored secret — the secret itself travels in every request. With HMAC, the secret never leaves your server. You recompute the expected signature from the payload and timestamp, then compare — so even if a request is intercepted in transit, the secret cannot be extracted from it.

Verifying in Node.js

const crypto = require('crypto');

function verifyWebhook(req) {
  const secret = process.env.OLIMI_WEBHOOK_SECRET; // the full whsec_... value
  const timestamp = req.headers['x-olimi-timestamp'];
  const signature = req.headers['x-olimi-signature'];

  // Missing headers means the webhook has no secret configured
  if (!timestamp || !signature) return false;

  // Reject requests older than 5 minutes to prevent replay attacks
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${req.rawBody}`)
    .digest('hex');

  // Guard required — timingSafeEqual throws on length mismatch
  if (signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

req.rawBody must be the raw request body bytes — not a parsed object. Computing HMAC over JSON.stringify(parsedBody) will fail if the serialization differs from what Olimi sent (e.g. key ordering, whitespace). In Express, capture raw bytes with express.raw({ type: 'application/json' }) before any JSON middleware.

Verifying in Python

import hmac
import hashlib
import time

def verify_webhook(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    # Reject requests older than 5 minutes
    if abs(time.time() - float(timestamp)) > 300:
        return False

    message = f"{timestamp}.{raw_body.decode('utf-8')}".encode()
    expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Example headers

X-Olimi-Timestamp: 1751234567
X-Olimi-Signature: sha256=3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c

Payload

{
  "id": "string",                  // Provider call SID (calls.call_sid)
  "contact_id": "string",          // Contact identifier (UUID), stable across attempts
  "phone_number": "string",        // Contact phone number in E.164
  "first_name":   "string | null", // Contact first name, null if no contact
  "last_name":    "string | null", // Contact last name, null if no contact
  "email":        "string | null", // Contact email address, null if no contact
  "duration": "integer",           // Call duration in SECONDS
  "summary_en": "string | null",   // AI-generated English summary
  "summary_ar": "string | null",   // AI-generated Arabic summary, null when not produced
  "is_interested": "boolean | null",// AI lead-qualification flag
  "tags": ["string"] | null,       // AI-extracted topical tags
  "call_time": "string",           // ISO-8601 timestamp of when the call was created
  "call_status": "string",         // pending | in_progress | answered | not_answered | failed
  "call_type": "string",           // inbound | outbound | web
  "transcript": [                  // Full conversation transcript messages
    {
      "id": "string",
      "role": "user | assistant | system",
      "content": "string",
      "metadata": "object | null",
      "createdAt": "string",
      "status": "string",
      "type": "string",
      "sentToTTS": "boolean",
      "spokenInCall": "boolean",
      "deleted": "boolean"
    }
  ],
  "custom_keys": [                 // AI-extracted key/value pairs
    { "key": "string", "value": "string" }
  ],
  "campaign": {                    // Present ONLY when the call belongs to a campaign
    "name": "string",
    "type": "string | null",
    "custom_metadata": [           // Array of single-key objects representing metadata
      { "key": "string" }
    ]
  },
  "is_final": "boolean",           // false when another webhook is still expected for this contact
  "agent_id": "string",            // Identifier of the agent that handled the call
  "is_transfered": "boolean",      // Whether the call was transferred to a human
  "callback_date": "string | null",// ISO-8601 (UTC) time of the scheduled callback, null when none
  "did_number": "string | null"    // Your Olimi number this call was placed on, null when none
}

Field reference

Field	Type	Description
`id`	string	External call identifier (the provider’s call SID).
`contact_id`	string (UUID)	The contact this call was placed to. Stable across retries and campaigns, so use it to correlate webhooks with your own records.
`phone_number`	string	Contact phone number in E.164 format.
`first_name`	string \| null	Contact first name. Null when no contact is attached.
`last_name`	string \| null	Contact last name. Null when no contact is attached.
`email`	string \| null	Contact email address. Null when no contact is attached.
`duration`	integer	Call duration in seconds.
`summary_en`	string \| null	AI-generated English summary of the conversation.
`summary_ar`	string \| null	AI-generated Arabic summary. Null when an Arabic summary was not produced.
`is_interested`	boolean \| null	Whether the AI classified the contact as interested.
`tags`	string[] \| null	Topical tags extracted by the AI.
`call_time`	string (ISO-8601)	When the call record was created, e.g. `2026-04-05T12:34:56+00:00`.
`call_status`	string	Outcome of the call attempt. See Call outcome fields below.
`call_type`	string	How the call was placed: `inbound`, `outbound`, or `web`.
`transcript`	object[]	Full conversation transcript messages. Empty array when no transcript was stored.
`custom_keys`	object[]	AI-extracted `{key, value}` pairs. See Custom keys below.
`campaign`	object	Present only when the call belongs to a campaign. See Campaign below.
`is_final`	boolean	Whether this is the last webhook you will receive for this contact attempt. See Call outcome fields below.
`agent_id`	string (UUID)	The agent that handled the call.
`is_transfered`	boolean	Whether the call was transferred to a human agent.
`callback_date`	string (ISO-8601) \| null	When a follow-up call is scheduled for this contact, in UTC. Null when no callback is due.
`did_number`	string \| null	The Olimi phone number this call was placed on, in E.164. Null when the call was not associated with one.

Call outcome fields

call_status is one of:

Value	Meaning
`pending`	Queued or ringing; the call has not been picked up yet.
`in_progress`	Currently connected.
`answered`	The contact answered and the conversation completed.
`not_answered`	No answer, busy, or rejected.
`failed`	The call could not be completed (telephony or network error).

is_final tells you whether to expect more. More than one webhook can arrive for the same contact — each attempt is delivered as its own call with its own id.

answered — final, unless a callback was scheduled during the conversation, in which case callback_date carries the UTC time of the follow-up and is_final is false.
not_answered / failed — final only when no campaign retry remains. If the campaign will dial again, is_final is false.
pending / in_progress — never final.

Treat is_final: true as the signal to close the record on your side; earlier deliveries are interim updates for the same contact.

Transcript items

Each transcript item includes detailed metadata and execution flags:

{
  "id": "msg_123",
  "role": "assistant",
  "content": "Hello, how can I help you today?",
  "metadata": {},
  "createdAt": "2026-04-05T12:30:00.000Z",
  "status": "completed",
  "type": "speech",
  "sentToTTS": true,
  "spokenInCall": true,
  "deleted": false
}

Observed roles: system, assistant, user.

Custom keys

Each custom key is an object with key and value:

{ "key": "callback_date", "value": "2026-04-10 15:00:00" }

The callback_date key, when present, is also consumed server-side to schedule a callback on the contact — you don’t need to act on it unless you want to mirror the behavior in your own system.

Campaign

Included only when the call belongs to a campaign.

Field	Type	Description
`name`	string	Campaign name.
`type`	string \| null	Campaign type identifier.
`custom_metadata`	object[]	Array of single-key metadata objects.

Example payload

{
  "id": "CA1234567890abcdef1234567890abcdef",
  "phone_number": "+201001234567",
  "first_name": "Sara",
  "last_name": "Ahmed",
  "email": "[email protected]",
  "duration": 180,
  "summary_en": "Caller asked about enrollment fees for the spring intake and requested a follow-up next week.",
  "summary_ar": "استفسرت المتصلة عن رسوم التسجيل لفصل الربيع وطلبت معاودة الاتصال الأسبوع القادم.",
  "is_interested": true,
  "tags": ["enrollment", "fees", "follow_up"],
  "call_time": "2026-04-05T12:34:56+00:00",
  "call_status": "answered",
  "call_type": "outbound",
  "transcript": [
    {
      "id": "msg_001",
      "role": "system",
      "content": "You are a helpful sales assistant...",
      "metadata": {},
      "createdAt": "2026-04-05T12:34:00.000Z",
      "status": "completed",
      "type": "system",
      "sentToTTS": false,
      "spokenInCall": false,
      "deleted": false
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Hello, how can I help you today?",
      "metadata": {},
      "createdAt": "2026-04-05T12:34:05.000Z",
      "status": "completed",
      "type": "speech",
      "sentToTTS": true,
      "spokenInCall": true,
      "deleted": false
    },
    {
      "id": "msg_003",
      "role": "user",
      "content": "I'd like to know about your spring program.",
      "metadata": {},
      "createdAt": "2026-04-05T12:34:10.000Z",
      "status": "completed",
      "type": "speech",
      "sentToTTS": false,
      "spokenInCall": false,
      "deleted": false
    }
  ],
  "custom_keys": [
    { "key": "callback_date",      "value": "2026-04-10 15:00:00" },
    { "key": "preferred_language", "value": "ar" }
  ],
  "campaign": {
    "name": "Spring 2026 Outreach",
    "type": "outbound",
    "custom_metadata": [
      { "source": "landing_page_v2" },
      { "region": "MENA" }
    ]
  },
  "is_final": false,
  "agent_id": "7f3c1e9a-2b64-4d18-9a05-6c1f0b3d8e42",
  "is_transfered": false,
  "callback_date": "2026-04-10T15:00:00.000Z",
  "did_number": "+20221234567"
}

is_final is false in this example because the conversation scheduled a callback — callback_date carries its UTC time, and a further webhook will follow that call.

Receiver expectations

Respond with any 2xx status to acknowledge receipt. Non-2xx responses trigger retries on our end.
Your endpoint must accept application/json request bodies.
Don’t rely on JSON key ordering — it is not guaranteed.
duration is in seconds. call_time and callback_date are ISO-8601 in UTC.
Expect more than one webhook per contact. Key your records off id (unique per call attempt) and use is_final to decide when the outcome is settled.
Treat unknown fields as additive and ignore them if you don’t need them.

Getting Started

API Overview

Agents & Campaigns

Speech

Webhooks setup

When a webhook fires

Request format

Signing secret

Signature verification

How the signature is constructed

Why HMAC over a Bearer token

Verifying in Node.js

Verifying in Python

Example headers

Payload

Field reference

Call outcome fields

Transcript items

Custom keys

Campaign

Example payload

Receiver expectations

​Webhooks setup

​When a webhook fires

​Request format

​Signing secret

​Signature verification

​How the signature is constructed

​Why HMAC over a Bearer token

​Verifying in Node.js

​Verifying in Python

​Example headers

​Payload

​Field reference

​Call outcome fields

​Transcript items

​Custom keys

​Campaign

​Example payload

​Receiver expectations

Webhooks setup

When a webhook fires

Request format

Signing secret

Signature verification

How the signature is constructed

Why HMAC over a Bearer token

Verifying in Node.js

Verifying in Python

Example headers

Payload

Field reference

Call outcome fields

Transcript items

Custom keys

Campaign

Example payload

Receiver expectations