Post-call webhooks

signed_content = <timestamp> + "." + <raw request body>
signature = "v1=" + hex(HMAC-SHA256(signing_secret, signed_content))

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const signingSecret = process.env.CARTRA_WEBHOOK_SECRET!;
const toleranceSeconds = 5 * 60;

function validSignature(
  rawBody: Buffer,
  timestamp: string,
  providedSignature: string,
): boolean {
  if (!/^\d+$/.test(timestamp)) return false;
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > toleranceSeconds) return false;

  const expected = createHmac("sha256", signingSecret)
    .update(timestamp)
    .update(".")
    .update(rawBody)
    .digest("hex");
  const provided = providedSignature.startsWith("v1=")
    ? providedSignature.slice(3)
    : "";

  const expectedBytes = Buffer.from(expected, "hex");
  const providedBytes = Buffer.from(provided, "hex");
  return (
    expectedBytes.length === providedBytes.length &&
    timingSafeEqual(expectedBytes, providedBytes)
  );
}

app.post(
  "/webhooks/cartra",
  express.raw({ type: "application/json" }),
  async (request, response) => {
    const rawBody = request.body as Buffer;
    const timestamp = request.header("x-cartra-webhook-timestamp") ?? "";
    const signature = request.header("x-cartra-webhook-signature") ?? "";
    const webhookId = request.header("x-cartra-webhook-id") ?? "";

    if (!validSignature(rawBody, timestamp, signature)) {
      return response.sendStatus(401);
    }

    const event = JSON.parse(rawBody.toString("utf8"));
    if (event.id !== webhookId) {
      return response.sendStatus(400);
    }

    // Insert webhookId and rawBody into durable storage or a queue.
    // Enforce a unique constraint on webhookId and treat duplicates as success.
    await durablyAcceptWebhook(webhookId, event);

    return response.sendStatus(204);
  },
);

import hashlib
import hmac
import json
import os
import time

from fastapi import FastAPI, HTTPException, Request, Response

app = FastAPI()
signing_secret = os.environ["CARTRA_WEBHOOK_SECRET"].encode()
tolerance_seconds = 5 * 60


@app.post("/webhooks/cartra")
async def receive_cartra_webhook(request: Request) -> Response:
    raw_body = await request.body()
    timestamp = request.headers.get("x-cartra-webhook-timestamp", "")
    provided_signature = request.headers.get("x-cartra-webhook-signature", "")
    webhook_id = request.headers.get("x-cartra-webhook-id", "")

    if not timestamp.isdigit():
        raise HTTPException(status_code=401)
    if abs(int(time.time()) - int(timestamp)) > tolerance_seconds:
        raise HTTPException(status_code=401)

    signed_content = timestamp.encode() + b"." + raw_body
    expected_signature = "v1=" + hmac.new(
        signing_secret,
        signed_content,
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected_signature, provided_signature):
        raise HTTPException(status_code=401)

    event = json.loads(raw_body)
    if event.get("id") != webhook_id:
        raise HTTPException(status_code=400)

    # Persist or enqueue using webhook_id as a unique idempotency key.
    await durably_accept_webhook(webhook_id, event)
    return Response(status_code=204)

{
  "id": "5e938027-cc8d-4cb8-86b8-78b390be44c6",
  "type": "call.ended",
  "api_version": "v1",
  "created_at": "2026-07-24T18:25:04.123Z",
  "data": {
    "call": {},
    "transcript": [],
    "transfer": {},
    "extracted_data": {}
  }
}

{
  "id": "5e938027-cc8d-4cb8-86b8-78b390be44c6",
  "type": "call.ended",
  "api_version": "v1",
  "created_at": "2026-07-24T18:25:04.123Z",
  "data": {
    "call": {
      "id": "93ea83ec-5ec7-4031-8597-4641f8898ee2",
      "room_name": "call-93ea83ec",
      "tenant_id": "1e52c246-a8aa-4655-89c8-89e037f86c57",
      "agent": {
        "id": "82ea1090-0649-426c-ac99-c6a07ab778e8",
        "name": "customer-service-agent",
        "display_name": "Customer Service"
      },
      "caller_phone": "+15555550100",
      "recipient_phone": "+15555550101",
      "channel": "phone",
      "direction": "inbound",
      "status": "completed",
      "started_at": "2026-07-24T18:20:00.000Z",
      "ended_at": "2026-07-24T18:25:00.000Z",
      "duration_seconds": 300,
      "data_completeness": "full"
    },
    "transcript": [
      {
        "role": "user",
        "content": "Please remove Alex Smith from my policy on August 1.",
        "interrupted": false,
        "created_at": 1784917210.25
      },
      {
        "role": "assistant",
        "content": "I can help with that. What is the reason for the removal?",
        "interrupted": false,
        "created_at": 1784917212.5
      },
      {
        "role": "user",
        "content": "They moved out of the household.",
        "interrupted": false,
        "created_at": 1784917218.75
      },
      {
        "role": "tool_call",
        "name": "warm_transfer_to_human",
        "arguments": "{\"destination\":\"service\"}",
        "call_id": "call_transfer_1"
      },
      {
        "role": "tool_result",
        "name": "warm_transfer_to_human",
        "output": "warm_transfer=completed; destination=Service team (+15555550123); reason=service",
        "is_error": false
      }
    ],
    "transfer": {
      "attempted": true,
      "type": "warm",
      "status": "completed",
      "reason_code": "transfer_completed",
      "verification": "human_confirmed",
      "destination": {
        "key": "service",
        "label": "Service team",
        "address": "+15555550123"
      },
      "attempts": [
        {
          "number": 1,
          "type": "warm",
          "status": "completed",
          "reason_code": "transfer_completed",
          "verification": "human_confirmed",
          "destination": {
            "key": "service",
            "label": "Service team",
            "address": "+15555550123"
          },
          "started_at": "2026-07-24T18:23:10.000Z",
          "ended_at": "2026-07-24T18:23:31.000Z"
        }
      ]
    },
    "extracted_data": {
      "status": "completed",
      "scopes": [
        {
          "scope": {
            "kind": "procedure",
            "key": "remove_drivers",
            "occurrence": 1
          },
          "status": "completed",
          "data": {
            "drivers_to_remove": [
              {
                "driver_full_name": "Alex Smith",
                "desired_effective_date": "2026-08-01",
                "removal_reason": "Moved out of the household"
              }
            ]
          },
          "diagnostics": [
            {
              "path": "/drivers_to_remove/0/driver_full_name",
              "status": "extracted",
              "evidence_message_ids": [0]
            },
            {
              "path": "/drivers_to_remove/0/desired_effective_date",
              "status": "extracted",
              "evidence_message_ids": [0]
            },
            {
              "path": "/drivers_to_remove/0/removal_reason",
              "status": "extracted",
              "evidence_message_ids": [2]
            }
          ]
        }
      ]
    }
  }
}

{
  "role": "user",
  "content": "Message text",
  "interrupted": false,
  "created_at": 1784917210.25
}

{
  "role": "tool_call",
  "name": "tool_name",
  "arguments": "{\"example\":\"value\"}",
  "call_id": "optional-call-id"
}

{
  "role": "tool_result",
  "name": "tool_name",
  "output": "Tool output",
  "is_error": false
}

{
  "role": "agent_handoff",
  "old_agent_id": "old-agent",
  "new_agent_id": "new-agent"
}

{
  "attempted": false,
  "type": null,
  "status": "not_attempted",
  "reason_code": null,
  "verification": null,
  "destination": null,
  "attempts": []
}