Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Refresh admin-guide webhooks event vocabulary to document recording.transcription.started, recording.events.extracted and recording.updated which are wired in master, including their actual payload shapes; note that recording.updated is not yet debounced

Murtaza Nasira9199ca5585b
diff --git a/docs/admin-guide/webhooks.md b/docs/admin-guide/webhooks.md
index a9611ff0..6c0ad769 100644
--- a/docs/admin-guide/webhooks.md
+++ b/docs/admin-guide/webhooks.md
@@ -13,19 +13,27 @@ or programmatically via the `/api/v1/webhooks` API.
| Event | Fired when | Payload `data` fields |
|---|---|---|
| `recording.created` | A recording row is created (upload arrived) | `recording_id`, `title`, `file_size`, `original_filename` |
+| `recording.transcription.started` | Worker picks up a transcribe or reprocess-transcription job and the audio file is on disk | `recording_id`, `title` |
| `recording.transcription.completed` | Transcription job finished successfully | `recording_id`, `title`, `language`, `audio_duration_seconds`, `transcription_duration_seconds` |
| `recording.transcription.failed` | Transcription failed permanently (retries exhausted) | `recording_id`, `title`, `error` |
| `recording.summary.completed` | Summary generated successfully | `recording_id`, `title`, `summarization_duration_seconds` |
| `recording.summary.failed` | Summary failed permanently | `recording_id`, `title`, `error` |
-| `recording.events.extracted` | Calendar event extraction finished and produced at least one event | `recording_id`, `events_count` |
-| `recording.updated` | Title, tags, folder, notes, or speakers changed (debounced; one per recording per 30 s) | `recording_id`, `fields_changed` |
+| `recording.events.extracted` | Calendar event extraction finished and produced at least one event | `recording_id`, `title`, `events_count` |
+| `recording.updated` | Title, participants, notes, summary, meeting_date, is_inbox, is_highlighted, or folder_id changed via `PATCH /api/v1/recordings/{id}` | `recording_id`, `title`, `fields_changed` (list of strings) |
| `recording.deleted` | Recording removed | `recording_id`, `title` |
| `webhook.test` | Synthetic event from the **Test** button or `POST /api/v1/webhooks/{id}/test` | `reason`, `webhook_id` |
-Only `recording.created`, `recording.transcription.*`, `recording.summary.*`,
-and `recording.deleted` are wired in the current backend. The remaining
-events are reserved in the vocabulary and will fire as the corresponding
-code paths gain webhook emission.
+All events listed above fire in the current backend. The
+`recording.transcription.started` event fires only after the audio
+file's existence on disk is confirmed, so subscribers don't see
+misleading started→failed sequences for jobs that abort immediately
+(e.g. the audio file was deleted between upload and worker pickup).
+
+The `recording.updated` event is **not currently debounced**. Rapid
+edits (e.g. notes autosave, drag-drop tag changes) emit one event per
+mutation. Receivers that want to coalesce can deduplicate on
+`(recording_id, fields_changed)` within a short window. A built-in
+debounce is planned for a later release (see `docs/roadmap.md`).
## Envelope