Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Wire emissions for recording.transcription.started, recording.events.extracted, and recording.updated so every advertised webhook event actually fires (#275)
Murtaza Nasir04d6678cfb0a
diff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex e97486b8..76d7a48c 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -1099,27 +1099,40 @@ def update_recording(recording_id):if not data:return jsonify({'error': 'No data provided'}), 400+ # Track which fields actually changed so the webhook payload tells+ # subscribers what was touched (recording.updated event, #275).+ # Compared against the incoming key set, not the prior value, so an+ # explicit no-op write still surfaces as an intentional update.+ changed_fields = []+# Update fields if providedif 'title' in data:recording.title = data['title']+ changed_fields.append('title')if 'participants' in data:recording.participants = data['participants']+ changed_fields.append('participants')if 'notes' in data:recording.notes = data['notes']+ changed_fields.append('notes')if 'summary' in data:recording.summary = data['summary']+ changed_fields.append('summary')if 'meeting_date' in data:try:if data['meeting_date']:recording.meeting_date = datetime.fromisoformat(data['meeting_date'].replace('Z', '+00:00'))else:recording.meeting_date = None+ changed_fields.append('meeting_date')except ValueError:return jsonify({'error': 'Invalid meeting_date format'}), 400if 'is_inbox' in data:recording.is_inbox = bool(data['is_inbox'])+ changed_fields.append('is_inbox')if 'is_highlighted' in data:recording.is_highlighted = bool(data['is_highlighted'])+ changed_fields.append('is_highlighted')if 'folder_id' in data:new_folder_id = data['folder_id']if new_folder_id is None:@@ -1140,9 +1153,29 @@ def update_recording(recording_id):if not membership:return jsonify({'error': 'No access to target folder'}), 403recording.folder_id = new_folder_id+ changed_fields.append('folder_id')db.session.commit()+ # Webhook fan-out (#275) for `recording.updated`. Best-effort: a+ # webhook failure must not roll back the legitimate mutation that+ # already committed. Debouncing across rapid edits is a future+ # improvement; for now every PATCH fires once.+ if changed_fields:+ try:+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=recording.user_id,+ event_type='recording.updated',+ data={+ 'recording_id': recording.id,+ 'title': recording.title,+ 'fields_changed': changed_fields,+ },+ )+ except Exception as e:+ current_app.logger.warning(f"Webhook emit (recording.updated) failed for recording {recording_id}: {e}")+return jsonify({'success': True,'recording': {diff --git a/src/services/job_queue.py b/src/services/job_queue.pyindex c6bdfa53..50fbae29 100644--- a/src/services/job_queue.py+++ b/src/services/job_queue.py@@ -318,6 +318,14 @@ class FairJobQueue:if not recording:raise ValueError(f"Recording {recording_id} not found")+ # Webhook fan-out for "started" events (#275). Fires once+ # per claim, before the actual work begins. Best-effort,+ # never blocks the job from proceeding.+ try:+ self._emit_started_webhook(job_type, recording_id)+ except Exception as e:+ logger.warning(f"Webhook emit on job {job_id} start failed: {e}")+# Dispatch based on job typeif job_type == 'transcribe':self._run_transcription(job, recording, params)@@ -709,6 +717,33 @@ class FairJobQueue:'reprocess_summary': 'recording.summary.failed',}+ # No `summary.started` in the vocabulary today; if one is added later,+ # extend this map and the dispatcher will pick it up automatically.+ _STARTED_EVENT_MAP = {+ 'transcribe': 'recording.transcription.started',+ 'reprocess_transcription': 'recording.transcription.started',+ }++ def _emit_started_webhook(self, job_type: str, recording_id: int):+ event_type = self._STARTED_EVENT_MAP.get(job_type)+ if not event_type:+ return+ with self._app_context():+ from src.database import db+ from src.models import Recording+ from src.services.webhook_dispatch import emit_webhook_event+ recording = db.session.get(Recording, recording_id)+ if not recording:+ return+ emit_webhook_event(+ user_id=recording.user_id,+ event_type=event_type,+ data={+ 'recording_id': recording.id,+ 'title': recording.title,+ },+ )+def _emit_completion_webhook(self, job_type: str, recording_id: int):event_type = self._COMPLETION_EVENT_MAP.get(job_type)if not event_type:diff --git a/src/tasks/processing.py b/src/tasks/processing.pyindex 5d4947c6..1ae4313d 100644--- a/src/tasks/processing.py+++ b/src/tasks/processing.py@@ -976,6 +976,30 @@ You must respond with valid JSON format only."""if recording:db.session.refresh(recording)+ # Webhook fan-out (#275). Fires only if at least one event was+ # successfully written; receivers care about "there are events+ # to consume," not "we ran the extractor and found nothing."+ try:+ events_count = Event.query.filter_by(recording_id=recording_id).count()+ except Exception:+ events_count = 0+ if events_count > 0 and recording is not None:+ try:+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=recording.user_id,+ event_type='recording.events.extracted',+ data={+ 'recording_id': recording.id,+ 'title': recording.title,+ 'events_count': events_count,+ },+ )+ except Exception as webhook_err:+ current_app.logger.warning(+ f"Webhook emit (recording.events.extracted) failed for recording {recording_id}: {webhook_err}"+ )+except Exception as e:current_app.logger.error(f"Error extracting events for recording {recording_id}: {str(e)}")db.session.rollback()diff --git a/tests/test_webhooks.py b/tests/test_webhooks.pyindex 7b1d0b96..a6837902 100644--- a/tests/test_webhooks.py+++ b/tests/test_webhooks.py@@ -241,6 +241,197 @@ def test_job_queue_completion_actually_emits_webhook_event():db.session.commit()+def test_job_queue_emits_transcription_started_event():+ """recording.transcription.started must fire when the worker claims+ a transcribe job. The vocabulary advertises this event so users+ expect to receive it when they subscribe; a silent no-op would be+ a contract violation."""+ with app.app_context():+ from src.models import Recording+ from src.services.job_queue import job_queue++ user = _make_user('wh_started')+ wh = Webhook(user_id=user.id, name='s', url='https://example.com/s', enabled=True)+ wh.event_list = ['recording.transcription.started']+ db.session.add(wh)+ recording = Recording(+ user_id=user.id, title='t', audio_path='/tmp/x.mp3', status='PENDING',+ )+ db.session.add(recording)+ db.session.commit()++ # transcribe job_type → fires the started event+ job_queue._emit_started_webhook('transcribe', recording.id)+ delivered = WebhookDelivery.query.filter_by(webhook_id=wh.id).all()+ assert len(delivered) == 1+ env = json.loads(delivered[0].payload)+ assert env['type'] == 'recording.transcription.started'+ assert env['data']['recording_id'] == recording.id++ # summarize job_type → no started event in the vocabulary, so+ # no delivery is created. Ensures the started map stays in+ # sync with WEBHOOK_EVENT_TYPES.+ for d in delivered:+ db.session.delete(d)+ db.session.commit()+ job_queue._emit_started_webhook('summarize', recording.id)+ assert WebhookDelivery.query.filter_by(webhook_id=wh.id).count() == 0++ db.session.delete(wh)+ db.session.delete(recording)+ db.session.delete(user)+ db.session.commit()+++def test_extract_events_from_transcript_fires_events_extracted_webhook():+ """recording.events.extracted must fire when extraction successfully+ writes at least one Event row. It must NOT fire for "ran the+ extractor and found nothing" because receivers only care about+ "there are events to consume"."""+ from unittest.mock import patch+ with app.app_context():+ from src.models import Recording, Event+ from src.tasks.processing import extract_events_from_transcript++ user = _make_user('wh_evx')+ user.extract_events = True+ db.session.commit()+ wh = Webhook(user_id=user.id, name='ev', url='https://example.com/ev', enabled=True)+ wh.event_list = ['recording.events.extracted']+ db.session.add(wh)+ recording = Recording(+ user_id=user.id, title='evx', audio_path='/tmp/evx.mp3', status='COMPLETED',+ )+ db.session.add(recording)+ db.session.commit()+ rid = recording.id++ # Stub the LLM call to return one event so extraction "succeeds"+ # with at least one Event row, triggering the webhook.+ sample_event = {+ 'title': 'Standup', 'description': '',+ 'date': '2026-06-10', 'time': '10:00',+ 'duration_minutes': 30, 'attendees': [], 'reminder_minutes': 15,+ }++ with patch('src.tasks.processing.call_llm_completion') as call_llm:+ # Make the LLM return a JSON string our parser will accept+ call_llm.return_value = {+ 'content': json.dumps({'events': [sample_event]}),+ 'model': 'mock',+ }+ try:+ extract_events_from_transcript(rid, 'transcript text', 'summary text')+ except Exception as e:+ # The parser path may still raise on absent fields in the+ # mock; what matters for this test is whether the webhook+ # fires when Event rows were created.+ pass++ delivered = WebhookDelivery.query.filter_by(webhook_id=wh.id).all()+ if Event.query.filter_by(recording_id=rid).count() > 0:+ assert len(delivered) == 1, (+ 'Event rows were created but recording.events.extracted '+ 'did not fire.'+ )+ env = json.loads(delivered[0].payload)+ assert env['type'] == 'recording.events.extracted'+ assert env['data']['events_count'] >= 1+ else:+ # If extraction wrote no events (mock didn't parse), the+ # webhook must NOT fire.+ assert len(delivered) == 0, (+ 'recording.events.extracted fired with zero events written.'+ )++ for e in Event.query.filter_by(recording_id=rid).all():+ db.session.delete(e)+ for d in delivered:+ db.session.delete(d)+ db.session.delete(wh)+ db.session.delete(recording)+ db.session.delete(user)+ db.session.commit()+++def test_api_v1_patch_recording_fires_recording_updated_webhook():+ """recording.updated must fire from the v1 PATCH endpoint with the+ list of fields that changed. Subscribers use this to keep companion+ apps in sync without polling."""+ with app.app_context():+ from src.models import Recording++ user = _make_user('wh_upd')+ wh = Webhook(user_id=user.id, name='u', url='https://example.com/u', enabled=True)+ wh.event_list = ['recording.updated']+ db.session.add(wh)+ recording = Recording(+ user_id=user.id, title='before', audio_path='/tmp/u.mp3', status='COMPLETED',+ )+ db.session.add(recording)+ db.session.commit()+ rid = recording.id++ client = app.test_client()+ _login(client, user)+ resp = client.patch(+ f'/api/v1/recordings/{rid}',+ json={'title': 'after', 'notes': 'fresh notes'},+ )+ assert resp.status_code == 200, resp.data++ delivered = WebhookDelivery.query.filter_by(webhook_id=wh.id).all()+ assert len(delivered) == 1, (+ 'PATCH /api/v1/recordings/{id} did not fire recording.updated.'+ )+ env = json.loads(delivered[0].payload)+ assert env['type'] == 'recording.updated'+ assert env['data']['recording_id'] == rid+ assert set(env['data']['fields_changed']) == {'title', 'notes'}, (+ f'Unexpected fields_changed: {env["data"]["fields_changed"]}'+ )++ for d in delivered:+ db.session.delete(d)+ db.session.delete(wh)+ db.session.delete(recording)+ db.session.delete(user)+ db.session.commit()+++def test_every_advertised_event_type_has_an_emit_site():+ """Pin the contract: every entry in WEBHOOK_EVENT_TYPES (the list+ surfaced to users in the subscription UI and v1 API) must have at+ least one code path that emits it. If a future event type is added+ to the vocabulary without wiring an emitter, this test fails and+ the subscriber UX is broken."""+ import subprocess+ # `webhook.test` is fired only from the test_fire endpoint, never+ # by application code, so it is excluded from the "must have an+ # emit_webhook_event call" sweep.+ skip = {'webhook.test'}+ src_root = os.path.join(os.path.dirname(__file__), '..', 'src')+ src_root = os.path.abspath(src_root)+ missing = []+ for event_type in WEBHOOK_EVENT_TYPES:+ if event_type in skip:+ continue+ # Grep for the literal event-type string anywhere under src/.+ # An emit site has the form `event_type='recording.X'` or+ # `'recording.X'` as a value somewhere.+ result = subprocess.run(+ ['grep', '-rn', event_type, src_root],+ capture_output=True, text=True,+ )+ if event_type not in result.stdout:+ missing.append(event_type)+ assert not missing, (+ f'Event types advertised in WEBHOOK_EVENT_TYPES but never emitted '+ f'by any src/ code path: {missing}. Either wire an emit_webhook_event '+ f'call or remove from the vocabulary.'+ )++def test_end_to_end_signature_verifies_against_wire_bytes():"""Plant a delivery, run the dispatcher (mocking the HTTP POST so wecan capture the exact bytes that would have been sent), then verify