Receive Caretta webhooks

Caretta can send signed HTTPS webhooks when call data becomes available. Use webhooks to move transcripts, AI-generated meeting notes, and evaluated metrics into your own systems.

Quickstart

Add an endpoint

As an organisation administrator, open Settings → Webhooks → Add endpoint in Caretta and enter a public HTTPS URL.

Choose a delivery mode

Select individual events for the lowest latency, or choose a bundled call.ready event for one combined payload.

Save the signing secret

Copy the signing secret when Caretta shows it. It is displayed once. Store it in a secrets manager or encrypted environment variable.

Send a test

Select Send test for the endpoint. Caretta sends a webhook.test request.

Verify and acknowledge

Verify X-Caretta-Signature against the raw request body and return a 2xx response within 10 seconds.

Events

Event	Sent when	Key data
`call.completed`	A captured call finishes processing.	Call envelope and transcript.
`call.notes_ready`	AI-generated notes become available.	Markdown notes, summary, and next steps.
`call.metrics_ready`	Metric evaluation finishes.	Evaluated metrics, or an empty list with a skip reason.
`call.ready`	Every selected bundled component is ready.	Transcript plus the selected notes and/or metrics.
`webhook.test`	An administrator sends a test from Settings.	A test message.

Eligible calls are real calls longer than 60 seconds that have not been deleted. Calls lasting 60 seconds or less, and deleted calls, do not produce delivery events.

Choose a delivery strategy

Per-event delivery

Select any combination of call.completed, call.notes_ready, and call.metrics_ready. This is the default and sends each component as soon as it is ready. Use call.completed when you need one reliable event for every eligible call. Use call.metrics_ready when you need the evaluation result for every eligible call, including calls that were skipped with a recorded reason.

Bundled delivery

Bundled mode sends one call.ready event after all selected components are ready. The transcript is always included; notes and metrics are optional.

Notes are best-effort. Roughly 3–4% of calls never generate notes, usually because the desktop app is closed before generation completes and is not reopened. In that case, call.notes_ready is not sent and a bundle that requires notes is never delivered. Notes may also arrive seconds or minutes after the transcript, and occasionally hours later.

If you must receive every eligible call:

Subscribe to call.completed using per-event delivery.
For a reliable single bundle, include metrics but do not require notes.
If you need a notes-and-metrics bundle, add a second per-event endpoint for call.completed as a safety net.

You can configure multiple endpoints and mix delivery modes.

Verify signatures

Every request includes these headers:

Header	Description
`X-Caretta-Signature`	`v1=` followed by the hexadecimal HMAC-SHA256 signature.
`X-Caretta-Timestamp`	Unix timestamp in seconds. Reject requests more than five minutes old.
`X-Caretta-Delivery-Id`	Identifier for one delivery attempt. Network retries reuse it.
`X-Caretta-Event-Id`	Stable idempotency key for the event. Retries reuse it.

Caretta signs this exact byte sequence:

{timestamp}.{raw request body}

with your endpoint secret as the HMAC-SHA256 key.

Verify the original raw request body. Parsing JSON and serialising it again can change whitespace or key order and will break signature verification.

verify-caretta-signature.js

const crypto = require("crypto");

function verifyCarettaSignature(req, secret) {
  const timestamp = req.headers["x-caretta-timestamp"];
  const signature = req.headers["x-caretta-signature"];

  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

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

  return (
    expected.length === signature.length &&
    crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signature)
    )
  );
}

Verify the signature before parsing or acting on the payload. Keep the endpoint secret server-side and rotate it if it may have been exposed.

Send an Authorization header

Some receivers cannot verify signatures and accept only a token in the Authorization header. For these receivers, enter the full header value in Authorization header when you add or edit the endpoint. For example:

Bearer your-receiver-token

Caretta stores the value encrypted and sends it unchanged as Authorization on every request, including test events. You cannot view the value after you save it. You can replace it or clear it. Requests are still signed, so you can verify the signature as well.

Use a token that your receiver issued. Do not use the Caretta signing secret as the Authorization header value.

Example: OpenClaw

OpenClaw hooks accept Authorization: Bearer <token>. In your OpenClaw config, enable hooks and add a mapping for Caretta. See OpenClaw inbound webhooks and hook configuration for all options.

{
  hooks: {
    enabled: true,
    token: "<long-random-hook-token>",
    mappings: [
      {
        match: { path: "caretta" },
        action: "agent",
        name: "Caretta {{event}}",
        messageTemplate: "Caretta sent a {{event}} webhook for call {{data.call.id}}. Notes: {{data.notes_markdown}}",
      },
    ],
  },
}

Then, in Caretta, set the endpoint URL to https://<your-openclaw-host>/hooks/caretta and the Authorization header to Bearer <long-random-hook-token>. The URL must be public HTTPS. To make OpenClaw reachable over HTTPS, see the OpenClaw exposure runbook. If a tunnel or reverse proxy sits in front of OpenClaw, also set its trusted proxies in the OpenClaw gateway configuration. Otherwise OpenClaw rejects the request with 403. OpenClaw limits hook requests to 256 KiB. A small number of call.completed events with very long transcripts can exceed this limit. If you need notes only, subscribe to call.notes_ready.

Delivery behaviour

Return any 2xx response within 10 seconds.
Delivery is at least once. Deduplicate using X-Caretta-Event-Id.
Event ordering is not guaranteed. Correlate related events with data.call.id.
Failed requests are retried with backoff for approximately two hours.
Network retries reuse the event and delivery IDs.

A good handler verifies the signature, stores or queues the event, returns 2xx, and performs slower processing asynchronously.

Payloads

All events include event, schema_version, event_id, delivery_id, and occurred_at.

call.completed

{
  "event": "call.completed",
  "schema_version": 1,
  "event_id": "evt_01J...",
  "delivery_id": "dlv_01J...",
  "occurred_at": "2026-07-14T18:42:11.000Z",
  "data": {
    "call": {
      "id": "call_01J...",
      "title": "Acme discovery",
      "duration_seconds": 1842,
      "owner": {
        "name": "Alex Morgan",
        "email": "alex@example.com"
      },
      "participants": [
        {
          "name": "Sam Lee",
          "email": "sam@acme.example"
        }
      ],
      "internal": false
    },
    "transcript": [
      {
        "speaker": "seller",
        "text": "Thanks for making the time today."
      },
      {
        "speaker": "client",
        "text": "Happy to be here."
      }
    ]
  }
}

call.notes_ready

{
  "event": "call.notes_ready",
  "schema_version": 1,
  "event_id": "evt_01J...",
  "delivery_id": "dlv_01J...",
  "occurred_at": "2026-07-14T18:44:32.000Z",
  "data": {
    "call": {
      "id": "call_01J..."
    },
    "notes_markdown": "## Summary\n...",
    "summary": "The team agreed to run a pilot.",
    "next_steps": [
      "Send the security questionnaire",
      "Schedule a technical review"
    ]
  }
}

call.metrics_ready

{
  "event": "call.metrics_ready",
  "schema_version": 1,
  "event_id": "evt_01J...",
  "delivery_id": "dlv_01J...",
  "occurred_at": "2026-07-14T18:45:08.000Z",
  "data": {
    "call": {
      "id": "call_01J..."
    },
    "metrics": [
      {
        "slug": "discovery-quality",
        "name": "Discovery quality",
        "value": 0.87,
        "confidence": 0.91,
        "evidence": "The seller confirmed the buyer's current process and impact.",
        "evaluated_at": "2026-07-14T18:45:08.000Z"
      }
    ]
  }
}

A completed evaluation can return an empty metrics array with a skip reason. Metrics can be re-evaluated; use evaluated_at to identify the latest result.

webhook.test

{
  "event": "webhook.test",
  "schema_version": 1,
  "event_id": "evt_01J...",
  "delivery_id": "dlv_01J...",
  "occurred_at": "2026-07-14T18:40:00.000Z",
  "data": {
    "message": "Caretta webhook test"
  }
}

Internal calls

Every data.call object has an internal field:

Value	Meaning
`true`	Only people from your company were in the meeting.
`false`	At least one person from outside your company was in the meeting.
`null`	Caretta could not tell, for example because the meeting has no attendee list.

Use it to skip internal meetings, for example to keep team calls out of your CRM.

These examples show the payload structure and use illustrative values. Build consumers to tolerate additional fields so they remain compatible as Caretta adds data.

Manage an endpoint

Open Settings → Webhooks to:

enable or disable delivery;
change the URL, subscribed events, or delivery mode;
set, replace, or clear the Authorization header;
send a test event;
inspect the delivery log;
rotate the signing secret; or
delete the endpoint.

Rotating the secret invalidates the previous secret immediately. Update your receiver before sending another test.

Endpoint management through a public REST API is planned but is not currently available.

Getting started

Integrations

Receive Caretta webhooks

Quickstart

Events

Choose a delivery strategy

Per-event delivery

Bundled delivery

Verify signatures

Send an Authorization header

Example: OpenClaw

Delivery behaviour

Payloads

Internal calls

Manage an endpoint

​Quickstart

​Events

​Choose a delivery strategy

​Per-event delivery

​Bundled delivery

​Verify signatures

​Send an Authorization header

​Example: OpenClaw

​Delivery behaviour

​Payloads

​Internal calls

​Manage an endpoint

Quickstart

Events

Choose a delivery strategy

Per-event delivery

Bundled delivery

Verify signatures

Send an Authorization header

Example: OpenClaw

Delivery behaviour

Payloads

Internal calls

Manage an endpoint