Text webhooks

Configure text webhooks in Settings → API & integrations. Use a spoken prefix, capture input, or recording type to choose what gets sent, or send a recording manually from its detail screen. Webhooks do not upload or deliver audio. Clips delete local audio after successful processing and a safe text save; Recordings retain it locally. This guide describes the existing /api/v1 interface. Use https://app.italic.com/api/v1 as the base URL for relative endpoints below. For simple v2 change notifications, see Webhooks. The v1 event feed covers writes from current and compatibility clients: recording.created, recording.updated, recording.transcript_ready, and recording.deleted. Created means the recording text resource was inserted; metadata-only pending captures do not emit a created event. Transcript-ready also fires when nonempty transcript text changes. GET /events?after=0&limit=100 returns account-scoped events, cursor, and hasMore. Persist the returned cursor after processing the page. IDs are monotonic but can have gaps. The feed currently remains until account deletion. Create subscriptions in web Settings. A public HTTPS endpoint on port 443 is required. Private/local addresses, credentials in the URL, and redirects are rejected. An account can have ten active subscriptions. The signing secret is shown once; retain it securely before dismissing it.

Verify before processing

The default event payload contains id, type, recordingId, revision, and createdAt. Existing subscriptions retain this shape. It contains no transcript, audio, or account bearer token. Fetch current content using a separately authorized read token when needed. The Italic-Signature header is t=<unix-seconds>,v1=<hex-hmac>. Compute HMAC-SHA256 with the webhook secret over the exact UTF-8 bytes of timestamp + "." + rawRequestBody. Compare the digest in constant time and reject timestamps more than five minutes from your server clock. Do not parse and reserialize the body before verification. Deduplicate by event id.

Delivery behavior

Delivery is at least once and may arrive out of order. A scheduled worker claims up to 20 deliveries per minute, with four concurrent requests and a five-second HTTP timeout. Any 2xx response acknowledges the event. Other statuses and network failures retry up to eight attempts with exponential backoff starting at one minute. Deliveries are persisted before sending; process crashes can produce a repeat. Exhausted deliveries remain recorded for diagnosis. Use the event feed to catch up independently of webhooks. Disabling a subscription cancels queued deliveries; an already dispatched request may still arrive. Recreate subscriptions after rotating the backend signing master (BETTER_AUTH_SECRET), because derived subscription secrets also change. Never rotate that authentication secret solely to rotate one webhook: disable and recreate the individual subscription instead.

Text payloads

Choose Recording text in settings or create a subscription with POST /webhooks and payloadMode: "text" using a signed-in account session. Text deliveries include an immutable snapshot of the selected revision. Retries retain the original body even if the recording was edited. Bodies exclude audio, coordinates, local files and credentials.

{
  "id": "123",
  "eventId": "123",
  "type": "recording.transcript_ready",
  "recordingId": "C5A80766-9674-4EE2-B238-63AC6DD51495",
  "revision": 1,
  "createdAt": 1790164800000,
  "kind": "clip",
  "title": "Parser fix",
  "transcript": "Codex fix the parser",
  "summary": "",
  "recordedAt": 1790164790000,
  "fetchUrl": "https://app.italic.com/api/v1/recordings/C5A80766-9674-4EE2-B238-63AC6DD51495",
  "command": "fix the parser"
}

fetchUrl requires separate authentication and returns the current revision. It is not a public download or a signed credential. Deletion events contain empty text and null kind/capture time. Deleting a recording erases its stored delivery text and cancels unstarted text deliveries. Previously delivered text is under the receiver’s control.

Capture rules

kind uses the existing values clip and memo; memo means a Recording.

{
  "url": "https://your-receiver.com/italic",
  "events": ["recording.transcript_ready"],
  "payloadMode": "text",
  "rules": {"prefix": "Codex", "captureInput": "hold", "kind": "clip"}
}

Every configured condition must match. Every matching subscription receives its own delivery. Prefixes are case-insensitive and anchored to the beginning of the transcript. The full transcript is preserved; command removes only the matched prefix and leading whitespace from the remainder. Capture rules apply once per subscription and newly admitted app/device recording, starting when the subscription is created. They use the first nonempty transcript. Later edits and MCP/API imports do not retrigger capture rules. Input conditions wait for authoritative capture metadata, including when it arrives after the transcript. Import-provided text is not a native capture. Subscriptions without rules keep their revision-based event behavior.

Manual delivery and status

Use Webhooks & delivery in a recording’s web or iOS detail. Setup remains in the authenticated web integration settings. The signed-in session API is:

POST /api/v1/recordings/{id}/deliveries
Idempotency-Key: send-2026-09-23-1
Content-Type: application/json

{"webhookId":"subscription-id","expectedRevision":3}

Manual sends bypass automatic rules and preserve the subscription’s payload mode. The event type is recording.manual, its ID begins with manual_, and it is not added to the recording-change feed. Reuse the same key and selection after a network failure. A stale revision is rejected, and disabled subscriptions cannot receive new sends. GET /api/v1/recordings/{id}/deliveries returns statuses and pending capture evaluations. Pending transcription, waiting for capture input, queued, delivered, failed and disabled are distinct states. Delivered means only that the receiver returned 2xx. The receiver owns starting, authorizing and tracking any downstream agent work. For each subscription, deduplicate on the payload’s id before starting a task.

Signature verification example (Node.js)

import {createHmac, timingSafeEqual} from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature ?? '');
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Start here

Integrations

Verify before processing

Delivery behavior

Text payloads

Capture rules

Manual delivery and status

Signature verification example (Node.js)

​Verify before processing

​Delivery behavior

​Text payloads

​Capture rules

​Manual delivery and status

​Signature verification example (Node.js)

Verify before processing

Delivery behavior

Text payloads

Capture rules

Manual delivery and status

Signature verification example (Node.js)