​

Webhooks

• URL — http:// or https:// (the platform does not enforce HTTPS; use it anyway). Delivery is subject to the platform’s outbound host policy: private addresses and disallowed hosts may be refused by the operator’s configuration, and such deliveries fail into the dead-letter queue.
• Event subscription — any subset of the three events below (default: call_ended + call_analyzed).
• Signing secret — configured on the platform side as a reference to a server-side secret (the name of an environment variable of the platform deployment); the value itself is never entered in the dashboard and is shared with you out of band.
• Agent — an endpoint is bound to exactly one live agent of the organization. The field is mandatory: an empty agent name is refused with webhooks.agent_required, an unknown or archived one with webhooks.agent_not_found. There is no organization-wide level — to cover several agents, register the endpoint on each of them (the same URL may be reused; agent_id in the payload tells them apart).
• Test events — an opt-in flag makes the endpoint also receive events of editor test sessions (mode: "test").
• Timeout — how long the platform waits for your 2xx (platform default 10 s, configurable per endpoint up to 120 s; 0 means the platform default).

​

Event envelope

Content-Type: application/json
User-Agent: conversation-flow-webhooks/1.0
X-CFlow-Event: call_ended
X-CFlow-Event-Id: evt-4f0c22b17a9d4e3c8b6a5f019e2d7c31
X-CFlow-Timestamp: 1753344187
X-CFlow-Signature: v1=6f2a45c1e8…

​

Which event arrives when

• call_ended — as soon as the session finishes, before analysis and usually before the recording is finalized. This is the early notification: transcript, call_status, status_reason, error_code, and the timing fields (answered_at, media_started_at, talk_from, talk_to). latency is present only when per-turn metrics were collected; its keys are the raw metric names ending in _ms (turn_ms, llm_ms, asr_ms, tts_ms, …) with values {avg, max} in milliseconds.
• call_analyzed — when both post-call pipelines are done: the analysis (terminal in any of done, skipped, failed, interrupted — the event is always delivered) and the recording finalization. The event is self-contained: full call block + analysis + ready recording. If you only need the final outcome, subscribe to call_analyzed alone and skip call_ended. Its call block is identical to call_ended.call except that the recording stays top-level and is not duplicated inside call.
• observer_incident — during the call, when a compliance observer configured on the agent detects a violation and its reaction includes a notification. Use it for real-time supervisor alerts. severity is low | medium | high (an unknown value is normalized to medium), confidence is 0–1 or null, mode may be "" when unknown. Multiple incidents in one call produce separate events; retries of the same incident keep the same event_id.
• ping — a test delivery from the dashboard button; agent_id is the agent the endpoint is bound to ("" for an organization-level endpoint). Respond 2xx and verify its signature like a real event. It is not retried.

​

Delivery semantics

• At-least-once. A delivery counts as successful only on a 2xx from your endpoint; anything else (non-2xx, timeout, connection error) is retried. You will receive duplicates — deduplicate on event_id.
• Retries with exponential backoff — platform settings, not per endpoint: by default up to 8 attempts with pauses of 30, 60, 120, 240, 480, 960 and 1920 seconds. After the final failed attempt the event moves to a dead-letter queue, from which an administrator can redeliver it manually (History → session details → webhook deliveries). Dead deliveries are purged after a retention period, so the manual-retry window is finite.
• Deliveries always go to the endpoint’s current URL, so a mistyped URL can be corrected and the event redelivered; an endpoint that was deleted or disabled sends its pending events straight to the dead-letter queue.
• Ordering is best-effort. call_ended is enqueued before call_analyzed, but delivery order is not guaranteed; observer_incident arrives mid-call. Treat each event independently, correlating by call_id.
• Respond fast. Return 2xx immediately after signature verification and process asynchronously: the platform waits at most the endpoint’s timeout.

​

Signature verification

signed_payload = "{X-CFlow-Timestamp}." + raw request body
X-CFlow-Signature: v1=<hex( HMAC-SHA256(secret, signed_payload) )>

import hashlib
import hmac
import time

def verify_webhook(
    secret: str,
    signature_header: str,   # X-CFlow-Signature, e.g. "v1=6f2a45…"
    timestamp_header: str,   # X-CFlow-Timestamp, e.g. "1753344187"
    raw_body: bytes,         # exact request body bytes
    tolerance_seconds: int = 300,
) -> bool:
    try:
        ts = int(timestamp_header)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > tolerance_seconds:
        return False  # replay protection
    signed = f"{ts}.".encode("utf-8") + raw_body
    expected = "v1=" + hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

const crypto = require("crypto");

function verifyWebhook(secret, signatureHeader, timestampHeader, rawBody, toleranceSeconds = 300) {
  const ts = parseInt(timestampHeader, 10);
  if (!Number.isFinite(ts)) return false;
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds) return false;
  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${ts}.`)
      .update(rawBody) // Buffer with the exact request bytes
      .digest("hex");
  const provided = Buffer.from(signatureHeader || "");
  const wanted = Buffer.from(expected);
  return provided.length === wanted.length && crypto.timingSafeEqual(provided, wanted);
}

​

Recordings