Skip to main content

Webhooks

A webhook tells a URL you control that something happened to a recording, as soon as it does. Use it to feed Zapier, n8n, Make, or your own backend. There is nothing to poll.

Add endpoints in the Vocci member center under Developer → Webhooks. Each account can have up to 10, and each endpoint chooses which events it receives (at least one).

Events​

EventSent when
session.completedThe transcript and the summary of a recording are both ready. This is the default.
audio.uploadedThe audio of a recording has finished uploading. It needs no transcription or subscription.

Both events share the same envelope: id, type, created_at, test and a data object with the session. The Vocci-Event-Type header carries the type.

session.completed​

Vocci sends it once the transcript and the summary of a recording are both ready. Regenerating a summary sends a new event for that recording.

POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: Vocci-Webhooks/1
Vocci-Event-Id: evt_0198f2c4-…_1
Vocci-Event-Type: session.completed
Vocci-Signature: t=1760000000,v1=5257a869…
{
  "id": "evt_0198f2c4-…_1",
  "type": "session.completed",
  "created_at": "2026-10-09T12:00:00.000Z",
  "test": false,
  "data": {
    "session": {
      "id": "0198f2c4-…",
      "title": "Weekly product sync",
      "started_at": "2026-10-09T11:30:00.000Z",
      "duration_seconds": 1800
    },
    "notes": { "markdown": "## Decisions\n- …", "truncated": false },
    "transcript": { "text": "[You] …", "truncated": false }
  }
}
FieldMeaning
idIdentifies one event. Retries and every endpoint receive the same id; dedupe on it.
testtrue for the sample sent when you add an endpoint or press Send test event.
data.notes.markdownThe summary notes, in Markdown.
data.transcript.textThe transcript, one speaker turn per line.
truncatedtrue when that text was cut to keep the request under 1 MB.

audio.uploaded​

Vocci sends it once a recording has finished uploading, when its session is created. It carries no notes or transcript, so it also reaches you when automatic transcription is off. Use it to hand the audio to your own transcription service or workflow.

Vocci-Event-Id: evt_0198f2c4-…_0
Vocci-Event-Type: audio.uploaded
{
  "id": "evt_0198f2c4-…_0",
  "type": "audio.uploaded",
  "created_at": "2026-10-09T11:36:12.000Z",
  "test": false,
  "data": {
    "session": {
      "id": "0198f2c4-…",
      "title": "Untitled",
      "started_at": "2026-10-09T11:30:00.000Z",
      "duration_seconds": 360
    },
    "audio_files": [
      {
        "id": "0198f2c4-…",
        "mime_type": "audio/mp4",
        "size_bytes": 5760000,
        "duration_seconds": 360,
        "download_url": "https://…",
        "expires_at": "2026-10-09T12:36:12.000Z"
      }
    ]
  }
}
FieldMeaning
idOne per recording session. Retries and every endpoint receive the same id; dedupe on it.
data.audio_filesThe audio files of the session, usually one.
data.audio_files[].download_urlA link to that file. It stops working at expires_at, one hour after this attempt was made.
data.audio_files[].duration_secondsThe length of that file, or null if it is not known.

The link is created for every delivery attempt, so a retry hours later carries a fresh one, and only once the file is in storage: if it has not landed yet, Vocci waits and retries instead of sending a link that fails. Download the file when the event arrives; the link is a credential, so do not share it or log it. Voice commands to the ring and AI chat recordings do not send this event.

Delivery​

  • Your endpoint must be public HTTPS. Private, internal, and Vocci addresses are refused.
  • Answer with any 2xx within 5 seconds. Redirects count as failures and are not followed.
  • A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 12 hours, and abandoned 24 hours after the first attempt.
  • The list in the member center shows the outcome of the latest delivery for each endpoint.
  • An endpoint only receives what happens after it was switched on; it never replays history. A recording whose session was created before the endpoint was switched on does not send audio.uploaded.
  • Changing an endpoint's events takes effect at once. An event from the last 24 hours that the endpoint newly subscribes to is delivered.

Test it​

Adding an endpoint, or choosing Send test event from its menu, sends one sample of each event the endpoint receives, with the same shape as a real one and "test": true. Map your Zapier trigger from those samples. The download_url in an audio.uploaded sample points to an example address and serves no file.

Always verify the signature before trusting a request.

Last updated on