Webhook payload and signature reference

Veura persists an event and exact request body before upload. The event ID and body remain stable across retries; the timestamp and signature are created for each attempt.

Updated 2026-11-1111 min readPlain Markdown

Request headers

HeaderValue
Content-Typeapplication/json, or multipart/form-data with a boundary when audio is included
X-Veura-Event-IDLowercase UUID for the persisted event; stable across retries
X-Veura-TimestampUnix timestamp in whole seconds for this delivery attempt
X-Veura-SignatureOptional v1 HMAC-SHA256 signature when a secret is configured

JSON payload

{
  "id": "3a50c8f4-59ab-4c44-b747-4f286e03ad57",
  "kind": "transcription.completed",
  "occurredAt": "2026-11-11T09:41:00Z",
  "record": {
    "id": "80ae1232-f07c-49cf-abde-451eb2a715eb",
    "title": "Launch announcement",
    "text": "Move the announcement to Thursday morning.",
    "summary": "Move the launch and prepare the customer email.",
    "createdAt": "2026-11-11T09:40:12Z",
    "recordedAt": "2026-11-11T09:39:26Z",
    "receivedAt": "2026-11-11T09:40:12Z",
    "duration": 46,
    "source": "index01",
    "sourceDeviceIdentifier": "index-device-id",
    "remoteRecordingIdentifier": "remote-recording-id",
    "requestsIndexAssistant": false,
    "model": "appleSpeech",
    "languageCode": "en",
    "audio": {
      "fileName": "recording.m4a",
      "checksum": "sha256-checksum",
      "byteCount": 734208,
      "format": "m4a"
    }
  }
}

Optional values are encoded as null or omitted according to the saved record. The source values are microphone, importedAudio, index01, and legacyUnknown. The kind is transcription.completed for completed notes and test for a manual endpoint test.

Multipart payload with audio

When audio is enabled and a saved audio file exists, Veura sends multipart/form-data. The event part is JSON with the field name event. The binary part uses the field name audio, the saved file name, and application/octet-stream.

--veura-boundary
Content-Disposition: form-data; name="event"
Content-Type: application/json

{...event JSON...}
--veura-boundary
Content-Disposition: form-data; name="audio"; filename="recording.m4a"
Content-Type: application/octet-stream

...binary audio...
--veura-boundary--

Verify the HMAC signature

Create the signing input from the UTF-8 bytes of v1:, the X-Veura-Timestamp value, one newline byte, and the exact request body bytes. Compute HMAC-SHA256 with the shared secret and compare the lowercase hexadecimal digest to the value after v1=.

signing_input = "v1:" + timestamp + "\n" + exact_body_bytes
signature = "v1=" + hex(HMAC_SHA256(secret, signing_input))

Node.js verification example

import crypto from "node:crypto";

export function verifyVeura(rawBody, timestamp, header, secret) {
  const prefix = Buffer.from(`v1:${timestamp}\n`, "utf8");
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(Buffer.concat([prefix, rawBody]))
    .digest("hex");

  const received = Buffer.from(header ?? "", "utf8");
  const calculated = Buffer.from(expected, "utf8");
  return received.length === calculated.length &&
    crypto.timingSafeEqual(received, calculated);
}