Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Webhooks Phase 1: models, dispatcher with HMAC + retry + SSRF guard, v1 CRUD, lifecycle event emission (#275)
Murtaza Nasir228ad15e62de
diff --git a/src/api/recordings.py b/src/api/recordings.pyindex 5bd81faf..c5c9de00 100644--- a/src/api/recordings.py+++ b/src/api/recordings.py@@ -2564,6 +2564,24 @@ def upload_file():)current_app.logger.info(f"Transcription job queued for recording ID: {recording.id}")+ # Webhook event (#275). Fan-out happens off-request via the+ # dispatcher; this call only enqueues a delivery row per matching+ # subscription, so it is cheap and safe inside the request path.+ try:+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=current_user.id,+ event_type='recording.created',+ data={+ 'recording_id': recording.id,+ 'title': recording.title,+ 'file_size': recording.file_size,+ 'original_filename': recording.original_filename,+ },+ )+ except Exception as e:+ current_app.logger.warning(f"Webhook emit (recording.created) failed: {e}")+response_data = recording.to_dict(viewer_user=current_user)if duplicate_warning:response_data['duplicate_warning'] = duplicate_warning@@ -2945,11 +2963,30 @@ def delete_recording(recording_id):if deleted_jobs > 0:current_app.logger.info(f"Deleted {deleted_jobs} processing jobs for recording {recording_id}")+ # Capture identity for the webhook event before deletion drops the row.+ _deleted_recording_id = recording.id+ _deleted_recording_title = recording.title+ _deleted_user_id = recording.user_id+# Delete the database record (cascade will handle chunks/embeddings)db.session.delete(recording)db.session.commit()current_app.logger.info(f"Deleted recording record ID: {recording_id}")+ # Webhook event (#275)+ try:+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=_deleted_user_id,+ event_type='recording.deleted',+ data={+ 'recording_id': _deleted_recording_id,+ 'title': _deleted_recording_title,+ },+ )+ except Exception as e:+ current_app.logger.warning(f"Webhook emit (recording.deleted) failed: {e}")+if ENABLE_INQUIRE_MODE and chunk_count > 0:current_app.logger.info(f"Successfully deleted embeddings and chunks for recording {recording_id}")diff --git a/src/api/webhooks.py b/src/api/webhooks.pynew file mode 100644index 00000000..cfd5755a--- /dev/null+++ b/src/api/webhooks.py@@ -0,0 +1,309 @@+"""User-facing webhook CRUD endpoints (#275).++Lives under ``/api/v1/webhooks`` and follows the same conventions as the+rest of the v1 API: login_required, JSON in/out, OpenAPI-documented.++The endpoints are exposed at ``/api/v1/webhooks*`` through registration+in ``api_v1.py`` (which is CSRF-exempt at the blueprint level), so the+CRUD operations also work for API-token authenticated clients.+"""++import os+from datetime import datetime++from flask import Blueprint, request, jsonify, current_app+from flask_login import login_required, current_user++from src.database import db+from src.models import Webhook, WebhookDelivery, WEBHOOK_EVENT_TYPES, generate_webhook_secret+from src.services.webhook_dispatch import (+ is_url_safe_for_webhook,+ emit_webhook_event,+)+++webhooks_bp = Blueprint('webhooks', __name__, url_prefix='/api/v1/webhooks')+++def _max_per_user() -> int:+ try:+ return max(1, int(os.environ.get('WEBHOOK_MAX_PER_USER', '10')))+ except (TypeError, ValueError):+ return 10+++def _load_owned(webhook_id: int):+ """Return the webhook if the current user owns it, else (None, 404 tuple)."""+ wh = db.session.get(Webhook, webhook_id)+ if wh is None or wh.user_id != current_user.id:+ return None, (jsonify({'error': 'Webhook not found'}), 404)+ return wh, None+++# ---- Collection ------------------------------------------------------------++@webhooks_bp.route('', methods=['GET'])+@login_required+def list_webhooks():+ """List the caller's webhooks."""+ rows = (+ Webhook.query+ .filter_by(user_id=current_user.id)+ .order_by(Webhook.created_at.desc())+ .all()+ )+ return jsonify({+ 'webhooks': [w.to_dict() for w in rows],+ 'event_types': list(WEBHOOK_EVENT_TYPES),+ 'max_per_user': _max_per_user(),+ })+++@webhooks_bp.route('', methods=['POST'])+@login_required+def create_webhook():+ """Create a webhook.++ Body: ``{name, url, events, allow_http=false, enabled=true}``.+ The newly-minted HMAC secret is returned **once** in this response;+ after that it is never exposed.+ """+ data = request.get_json(silent=True) or {}+ name = (data.get('name') or '').strip()+ url = (data.get('url') or '').strip()+ events = data.get('events') or []+ allow_http = bool(data.get('allow_http', False))+ enabled = bool(data.get('enabled', True))++ if not name:+ return jsonify({'error': 'name is required'}), 400+ if not url:+ return jsonify({'error': 'url is required'}), 400+ if not isinstance(events, list) or not events:+ return jsonify({'error': 'events must be a non-empty list'}), 400++ unknown = [e for e in events if e not in WEBHOOK_EVENT_TYPES]+ if unknown:+ return jsonify({+ 'error': f'unknown event types: {unknown}',+ 'allowed': list(WEBHOOK_EVENT_TYPES),+ }), 400++ ok, reason = is_url_safe_for_webhook(url, allow_http=allow_http)+ if not ok:+ return jsonify({'error': reason}), 400++ existing = Webhook.query.filter_by(user_id=current_user.id).count()+ if existing >= _max_per_user():+ return jsonify({+ 'error': f'Per-user webhook cap reached ({existing}/{_max_per_user()})',+ 'max_per_user': _max_per_user(),+ }), 409++ wh = Webhook(+ user_id=current_user.id,+ name=name[:100],+ url=url[:500],+ allow_http=allow_http,+ enabled=enabled,+ secret=generate_webhook_secret(),+ )+ try:+ wh.event_list = events+ except ValueError as e:+ return jsonify({'error': str(e)}), 400+ db.session.add(wh)+ db.session.commit()+ # Include the secret in the create response so the user can copy it+ # to their receiver. Subsequent reads omit it.+ return jsonify(wh.to_dict(include_secret=True)), 201+++# ---- Single resource -------------------------------------------------------++@webhooks_bp.route('/<int:webhook_id>', methods=['GET'])+@login_required+def get_webhook(webhook_id):+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ return jsonify(wh.to_dict())+++@webhooks_bp.route('/<int:webhook_id>', methods=['PATCH'])+@login_required+def update_webhook(webhook_id):+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ data = request.get_json(silent=True) or {}++ if 'name' in data:+ name = (data.get('name') or '').strip()+ if not name:+ return jsonify({'error': 'name cannot be empty'}), 400+ wh.name = name[:100]+ if 'url' in data or 'allow_http' in data:+ new_url = (data.get('url') or wh.url).strip()+ new_allow_http = bool(data.get('allow_http', wh.allow_http))+ ok, reason = is_url_safe_for_webhook(new_url, allow_http=new_allow_http)+ if not ok:+ return jsonify({'error': reason}), 400+ wh.url = new_url[:500]+ wh.allow_http = new_allow_http+ if 'events' in data:+ events = data.get('events') or []+ if not isinstance(events, list) or not events:+ return jsonify({'error': 'events must be a non-empty list'}), 400+ try:+ wh.event_list = events+ except ValueError as e:+ return jsonify({'error': str(e)}), 400+ if 'enabled' in data:+ enabled = bool(data.get('enabled'))+ wh.enabled = enabled+ if enabled:+ wh.auto_paused = False # Manual re-enable resets auto-pause flag++ db.session.commit()+ return jsonify(wh.to_dict())+++@webhooks_bp.route('/<int:webhook_id>', methods=['DELETE'])+@login_required+def delete_webhook(webhook_id):+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ db.session.delete(wh)+ db.session.commit()+ return ('', 204)+++# ---- Secret rotation -------------------------------------------------------++@webhooks_bp.route('/<int:webhook_id>/rotate-secret', methods=['POST'])+@login_required+def rotate_secret(webhook_id):+ """Generate a fresh HMAC secret and return it once."""+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ wh.secret = generate_webhook_secret()+ db.session.commit()+ return jsonify(wh.to_dict(include_secret=True))+++# ---- Test fire -------------------------------------------------------------++@webhooks_bp.route('/<int:webhook_id>/test', methods=['POST'])+@login_required+def test_fire(webhook_id):+ """Enqueue a synthetic ``webhook.test`` delivery against this webhook.++ Unlike ``emit_webhook_event`` which fans out to all subscribed+ webhooks for a user, this one targets a single webhook by id and+ bypasses the subscription check (so the user can verify reachability+ even before subscribing to any production events).+ """+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ if not wh.enabled:+ return jsonify({'error': 'Webhook is disabled; enable it first'}), 409++ import json+ import uuid+ from src.services.webhook_dispatch import _build_envelope # internal helper reuse+ event_id = str(uuid.uuid4())+ envelope = _build_envelope(event_id, 'webhook.test', current_user.id, {+ 'reason': 'manual test from /api/v1/webhooks/{id}/test',+ 'webhook_id': wh.id,+ })+ delivery = WebhookDelivery(+ webhook_id=wh.id,+ event_id=event_id,+ event_type='webhook.test',+ payload=json.dumps(envelope),+ status='pending',+ next_retry_at=datetime.utcnow(),+ )+ db.session.add(delivery)+ db.session.commit()+ return jsonify(delivery.to_dict()), 202+++# ---- Deliveries listing / replay ------------------------------------------++@webhooks_bp.route('/<int:webhook_id>/deliveries', methods=['GET'])+@login_required+def list_deliveries(webhook_id):+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ try:+ limit = min(200, max(1, int(request.args.get('limit', 50))))+ except (TypeError, ValueError):+ limit = 50+ rows = (+ WebhookDelivery.query+ .filter_by(webhook_id=wh.id)+ .order_by(WebhookDelivery.created_at.desc())+ .limit(limit)+ .all()+ )+ return jsonify({+ 'deliveries': [d.to_dict() for d in rows],+ 'limit': limit,+ })+++@webhooks_bp.route('/<int:webhook_id>/deliveries/<int:delivery_id>', methods=['GET'])+@login_required+def get_delivery(webhook_id, delivery_id):+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ d = db.session.get(WebhookDelivery, delivery_id)+ if not d or d.webhook_id != wh.id:+ return jsonify({'error': 'Delivery not found'}), 404+ payload = d.to_dict()+ payload['payload'] = d.payload # full body, for debugging+ return jsonify(payload)+++@webhooks_bp.route('/<int:webhook_id>/deliveries/<int:delivery_id>/replay', methods=['POST'])+@login_required+def replay_delivery(webhook_id, delivery_id):+ """Re-enqueue the delivery as a brand-new attempt with the same payload."""+ wh, err = _load_owned(webhook_id)+ if err:+ return err+ src = db.session.get(WebhookDelivery, delivery_id)+ if not src or src.webhook_id != wh.id:+ return jsonify({'error': 'Delivery not found'}), 404++ import uuid+ new_event_id = str(uuid.uuid4())+ # Update the envelope's id field so the receiver sees a fresh delivery id.+ try:+ import json as _json+ envelope = _json.loads(src.payload)+ envelope['id'] = new_event_id+ envelope['timestamp'] = datetime.utcnow().isoformat() + 'Z'+ envelope['replayed_from'] = src.event_id+ new_payload = _json.dumps(envelope)+ except Exception:+ new_payload = src.payload++ replay = WebhookDelivery(+ webhook_id=wh.id,+ event_id=new_event_id,+ event_type=src.event_type,+ payload=new_payload,+ status='pending',+ next_retry_at=datetime.utcnow(),+ )+ db.session.add(replay)+ db.session.commit()+ return jsonify(replay.to_dict()), 202diff --git a/src/app.py b/src/app.pyindex 6915e258..54cd7017 100644--- a/src/app.py+++ b/src/app.py@@ -625,6 +625,7 @@ from src.api.system import system_bp, init_system_helpersfrom src.api.push_notifications import push_bpfrom src.api.api_v1 import api_v1_bp, init_api_v1_helpersfrom src.api.recording_sessions import recording_sessions_bp+from src.api.webhooks import webhooks_bp# Database initialization (extracted to src/init_db.py)from src.init_db import initialize_database@@ -678,6 +679,12 @@ csrf.exempt(api_v1_bp) # API v1 uses token auth, not CSRF# the token, so no exemption is needed here.app.register_blueprint(recording_sessions_bp)+# Webhooks (#275): under /api/v1, CSRF-exempt so API-token clients can+# manage their endpoints programmatically. SPA callers still attach the+# X-CSRFToken header for cookie-auth requests.+app.register_blueprint(webhooks_bp)+csrf.exempt(webhooks_bp)+# PWA Web Share Target (issue #285): the native share sheet cannot round-trip# a CSRF token, so the share-target endpoint is exempted. Authentication still# happens via the session cookie carried by the browser; @login_requireddiff --git a/src/config/startup.py b/src/config/startup.pyindex dc28517f..b6140356 100644--- a/src/config/startup.py+++ b/src/config/startup.py@@ -202,3 +202,7 @@ def run_startup_tasks(app):# Initialize recording-session cleanup scheduler (#287 c/d)initialize_recording_session_cleanup(app)++ # Initialize webhook dispatcher (#275)+ from src.services.webhook_dispatch import start_dispatcher_thread+ start_dispatcher_thread(app)diff --git a/src/models/__init__.py b/src/models/__init__.pyindex 8d23e6c0..3ed3e257 100644--- a/src/models/__init__.py+++ b/src/models/__init__.py@@ -32,6 +32,13 @@ from .processing_job import ProcessingJobfrom .recording_session import RecordingSession, RECORDING_SESSION_STATUSESfrom .token_usage import TokenUsagefrom .transcription_usage import TranscriptionUsage+from .webhook import (+ Webhook,+ WebhookDelivery,+ WEBHOOK_EVENT_TYPES,+ WEBHOOK_DELIVERY_STATUSES,+ generate_webhook_secret,+)# Export all models__all__ = [@@ -69,4 +76,9 @@ __all__ = ['RECORDING_SESSION_STATUSES','TokenUsage','TranscriptionUsage',+ 'Webhook',+ 'WebhookDelivery',+ 'WEBHOOK_EVENT_TYPES',+ 'WEBHOOK_DELIVERY_STATUSES',+ 'generate_webhook_secret',]diff --git a/src/models/webhook.py b/src/models/webhook.pynew file mode 100644index 00000000..4d73a6d8--- /dev/null+++ b/src/models/webhook.py@@ -0,0 +1,219 @@+"""Webhook models for outbound event notifications (#275).++Two tables:++- ``webhook`` — the user-owned endpoint. Each row has a URL, an HMAC+ secret, a subscription list, and the running health counters+ (``consecutive_failures``, ``last_delivery_at``).+- ``webhook_delivery`` — per-attempt audit log. One row per fired event+ per webhook; the row tracks attempts, status code, response preview,+ and the next retry timestamp.++Design choices documented in ``temp/DESIGN_webhooks.md``.+"""++import json+import secrets+from datetime import datetime++from src.database import db+++WEBHOOK_EVENT_TYPES = (+ 'recording.created',+ 'recording.transcription.started',+ 'recording.transcription.completed',+ 'recording.transcription.failed',+ 'recording.summary.completed',+ 'recording.summary.failed',+ 'recording.events.extracted',+ 'recording.updated',+ 'recording.deleted',+ 'webhook.test',+)+++WEBHOOK_DELIVERY_STATUSES = (+ 'pending', # queued, not yet attempted+ 'success', # 2xx received+ 'failed', # last attempt was a retryable error; may be re-tried+ 'permanent_failure', # retries exhausted, or non-retryable status+)+++def generate_webhook_secret():+ """Return a URL-safe random secret used for HMAC signing.++ 256 bits of entropy is overkill for SHA-256 HMAC but keeps the+ output short and avoids any chance of collision pressure if we+ ever want to use the secret as an opaque lookup key elsewhere.+ """+ return secrets.token_urlsafe(32)+++class Webhook(db.Model):+ """A user-owned webhook endpoint that receives event notifications."""++ __tablename__ = 'webhook'++ id = db.Column(db.Integer, primary_key=True)+ user_id = db.Column(+ db.Integer,+ db.ForeignKey('user.id', ondelete='CASCADE'),+ nullable=False,+ index=True,+ )++ name = db.Column(db.String(100), nullable=False)+ url = db.Column(db.String(500), nullable=False)++ # When true, the endpoint may use http:// (intranet-only). Off by+ # default so an accidental misconfiguration cannot leak event payloads+ # in plain text. The SSRF guard in the dispatcher additionally+ # validates that the destination is not a private IP unless the+ # admin has explicitly allowlisted intranet hosts.+ allow_http = db.Column(db.Boolean, default=False, nullable=False)++ # HMAC signing secret. Treat as a credential: redact in API+ # responses, surface to the user only on creation, allow rotation+ # via a dedicated endpoint.+ secret = db.Column(db.String(120), nullable=False, default=generate_webhook_secret)++ # JSON array of event type strings the endpoint is subscribed to.+ # Validated against WEBHOOK_EVENT_TYPES on write.+ events = db.Column(db.Text, nullable=False, default='[]')++ # Toggleable by the user (and admin). Auto-paused (also flips this+ # to False) when consecutive_failures crosses WEBHOOK_AUTOPAUSE_FAILURES.+ enabled = db.Column(db.Boolean, default=True, nullable=False, index=True)+ auto_paused = db.Column(db.Boolean, default=False, nullable=False)++ consecutive_failures = db.Column(db.Integer, default=0, nullable=False)++ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)+ last_delivery_at = db.Column(db.DateTime, nullable=True)++ user = db.relationship(+ 'User',+ backref=db.backref('webhooks', lazy='dynamic', cascade='all, delete-orphan'),+ )+ deliveries = db.relationship(+ 'WebhookDelivery',+ back_populates='webhook',+ cascade='all, delete-orphan',+ lazy='dynamic',+ )++ def __repr__(self): # pragma: no cover+ return f'<Webhook {self.id} user={self.user_id} name={self.name!r} enabled={self.enabled}>'++ @property+ def event_list(self):+ """Decoded subscription list; empty list on missing/invalid JSON."""+ if not self.events:+ return []+ try:+ value = json.loads(self.events)+ except (TypeError, ValueError):+ return []+ if not isinstance(value, list):+ return []+ return [e for e in value if isinstance(e, str)]++ @event_list.setter+ def event_list(self, values):+ if values is None:+ self.events = '[]'+ return+ if not isinstance(values, (list, tuple)):+ raise ValueError('events must be a list')+ deduped = []+ seen = set()+ for v in values:+ if not isinstance(v, str):+ continue+ if v not in WEBHOOK_EVENT_TYPES:+ raise ValueError(f'Unknown webhook event type: {v!r}')+ if v in seen:+ continue+ seen.add(v)+ deduped.append(v)+ self.events = json.dumps(deduped)++ def to_dict(self, include_secret=False):+ """Public API view. ``include_secret`` is True only at creation+ time and on explicit rotation; never include the secret on list+ or get responses."""+ payload = {+ 'id': self.id,+ 'user_id': self.user_id,+ 'name': self.name,+ 'url': self.url,+ 'allow_http': bool(self.allow_http),+ 'events': self.event_list,+ 'enabled': bool(self.enabled),+ 'auto_paused': bool(self.auto_paused),+ 'consecutive_failures': self.consecutive_failures,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ 'last_delivery_at': self.last_delivery_at.isoformat() if self.last_delivery_at else None,+ }+ if include_secret:+ payload['secret'] = self.secret+ return payload+++class WebhookDelivery(db.Model):+ """A single delivery attempt (or attempt series) for one fired event."""++ __tablename__ = 'webhook_delivery'++ id = db.Column(db.Integer, primary_key=True)+ webhook_id = db.Column(+ db.Integer,+ db.ForeignKey('webhook.id', ondelete='CASCADE'),+ nullable=False,+ index=True,+ )++ # UUID written into the payload `id` field and the+ # Speakr-Delivery-Id header. Receivers use it for idempotency.+ event_id = db.Column(db.String(36), nullable=False, index=True)+ event_type = db.Column(db.String(80), nullable=False, index=True)++ # Serialised JSON envelope that gets POSTed. Stored verbatim so+ # replay re-uses the original signature payload.+ payload = db.Column(db.Text, nullable=False)++ attempt_count = db.Column(db.Integer, default=0, nullable=False)+ status = db.Column(db.String(20), default='pending', nullable=False, index=True)++ response_status = db.Column(db.Integer, nullable=True)+ response_body_preview = db.Column(db.String(2000), nullable=True)+ error_message = db.Column(db.String(500), nullable=True)++ next_retry_at = db.Column(db.DateTime, nullable=True, index=True)+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False, index=True)+ delivered_at = db.Column(db.DateTime, nullable=True)++ webhook = db.relationship('Webhook', back_populates='deliveries')++ def __repr__(self): # pragma: no cover+ return f'<WebhookDelivery {self.id} webhook={self.webhook_id} status={self.status}>'++ def to_dict(self):+ return {+ 'id': self.id,+ 'webhook_id': self.webhook_id,+ 'event_id': self.event_id,+ 'event_type': self.event_type,+ 'attempt_count': self.attempt_count,+ 'status': self.status,+ 'response_status': self.response_status,+ 'response_body_preview': self.response_body_preview,+ 'error_message': self.error_message,+ 'next_retry_at': self.next_retry_at.isoformat() if self.next_retry_at else None,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'delivered_at': self.delivered_at.isoformat() if self.delivered_at else None,+ }diff --git a/src/services/job_queue.py b/src/services/job_queue.pyindex 412a245c..4a5734ba 100644--- a/src/services/job_queue.py+++ b/src/services/job_queue.py@@ -340,6 +340,15 @@ class FairJobQueue:db.session.commit()logger.info(f"Job {job_id} completed successfully")+ # Webhook fan-out (#275). One emit per job-type completion;+ # subscribers map these to user-visible lifecycle events.+ # Best-effort: if the webhook subsystem throws, the job is+ # still marked completed.+ try:+ self._emit_completion_webhook(job_type, recording_id)+ except Exception as e:+ logger.warning(f"Webhook emit on job {job_id} completion failed: {e}")+except Exception as e:error_str = str(e)logger.error(f"Job {job_id} failed: {e}", exc_info=True)@@ -381,6 +390,15 @@ class FairJobQueue:else:logger.error(f"Job {job_id} failed permanently after {MAX_RETRIES} retries")+ # Webhook fan-out for permanent failure (#275). The+ # retryable-failure case does not emit because the+ # subscriber will see the eventual success or+ # permanent failure that follows the retry loop.+ try:+ self._emit_failure_webhook(job_type, recording_id, error_str)+ except Exception as e:+ logger.warning(f"Webhook emit on job {job_id} failure failed: {e}")+db.session.commit()def _run_transcription(self, job, recording, params):@@ -675,5 +693,66 @@ class FairJobQueue:logger.info(f"Cleaned up {deleted} old jobs")+ # --- Webhook emission helpers (#275) ---------------------------------++ _COMPLETION_EVENT_MAP = {+ 'transcribe': 'recording.transcription.completed',+ 'summarize': 'recording.summary.completed',+ 'reprocess_transcription': 'recording.transcription.completed',+ 'reprocess_summary': 'recording.summary.completed',+ }++ _FAILURE_EVENT_MAP = {+ 'transcribe': 'recording.transcription.failed',+ 'summarize': 'recording.summary.failed',+ 'reprocess_transcription': 'recording.transcription.failed',+ 'reprocess_summary': 'recording.summary.failed',+ }++ def _emit_completion_webhook(self, job_type: str, recording_id: int):+ event_type = self._COMPLETION_EVENT_MAP.get(job_type)+ if not event_type:+ return+ with self._app_context():+ from src.models import Recording+ recording = db.session.get(Recording, recording_id)+ if not recording:+ return+ data = {+ 'recording_id': recording.id,+ 'title': recording.title,+ 'language': getattr(recording, 'transcription_language', None),+ 'audio_duration_seconds': getattr(recording, 'audio_duration', None),+ 'transcription_duration_seconds': getattr(recording, 'transcription_duration_seconds', None),+ 'summarization_duration_seconds': getattr(recording, 'summarization_duration_seconds', None),+ }+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=recording.user_id,+ event_type=event_type,+ data={k: v for k, v in data.items() if v is not None},+ )++ def _emit_failure_webhook(self, job_type: str, recording_id: int, error: str):+ event_type = self._FAILURE_EVENT_MAP.get(job_type)+ if not event_type:+ return+ with self._app_context():+ from src.models import Recording+ recording = db.session.get(Recording, recording_id)+ if not recording:+ return+ from src.services.webhook_dispatch import emit_webhook_event+ emit_webhook_event(+ user_id=recording.user_id,+ event_type=event_type,+ data={+ 'recording_id': recording.id,+ 'title': recording.title,+ 'error': (error or '')[:500],+ },+ )++# Global job queue instancejob_queue = FairJobQueue()diff --git a/src/services/webhook_dispatch.py b/src/services/webhook_dispatch.pynew file mode 100644index 00000000..b8dec819--- /dev/null+++ b/src/services/webhook_dispatch.py@@ -0,0 +1,420 @@+"""Webhook dispatch service (#275).++Two responsibilities:++1. ``emit_webhook_event(user_id, event_type, data, *, app=None)`` — the+ call-site API. Cheap and synchronous: looks up the user's subscribed+ webhooks, creates a ``WebhookDelivery`` row per match, and returns.+ Safe to call from request handlers and from the job_queue worker.+2. ``run_dispatcher_pass(app)`` — the background sweep. Picks up+ ``pending`` deliveries plus ``failed`` deliveries whose+ ``next_retry_at`` has elapsed, POSTs them with the HMAC signature,+ and updates the row. Auto-pauses the parent webhook after N+ consecutive failures.++The dispatcher is launched from ``src/config/startup.py`` as a daemon+thread, matching the pattern used by the recording-session cleanup+sweep.++Security:++- HMAC-SHA256 signature in ``Speakr-Signature`` (``sha256=<hex>``).+- ``Speakr-Delivery-Id`` and ``Speakr-Event`` headers for idempotency+ and cheap routing.+- ``Speakr-Timestamp`` so receivers can reject stale deliveries.+- SSRF guard: outbound URLs are resolved and validated against a+ private-network blocklist. ``allow_http`` only opens the http://+ scheme; private hosts still require the admin allowlist.+"""++import hashlib+import hmac+import ipaddress+import json+import logging+import os+import re+import socket+import threading+import time+import uuid+from datetime import datetime, timedelta+from typing import Iterable+from urllib.parse import urlparse++import requests++from src.database import db+from src.models import Webhook, WebhookDelivery, WEBHOOK_EVENT_TYPES+++logger = logging.getLogger(__name__)+++# ---- Config knobs (read fresh each call so tests can patch env) ------------++def _delivery_timeout() -> float:+ try:+ return float(os.environ.get('WEBHOOK_DELIVERY_TIMEOUT_SECONDS', '10'))+ except (TypeError, ValueError):+ return 10.0+++def _max_attempts() -> int:+ try:+ return max(1, int(os.environ.get('WEBHOOK_MAX_ATTEMPTS', '5')))+ except (TypeError, ValueError):+ return 5+++def _autopause_failures() -> int:+ try:+ return max(1, int(os.environ.get('WEBHOOK_AUTOPAUSE_FAILURES', '10')))+ except (TypeError, ValueError):+ return 10+++def _dispatcher_interval() -> int:+ try:+ return max(1, int(os.environ.get('WEBHOOK_DISPATCHER_INTERVAL_SECONDS', '5')))+ except (TypeError, ValueError):+ return 5+++def _max_per_user() -> int:+ try:+ return max(1, int(os.environ.get('WEBHOOK_MAX_PER_USER', '10')))+ except (TypeError, ValueError):+ return 10+++def _global_enabled() -> bool:+ return os.environ.get('WEBHOOK_GLOBAL_ENABLED', 'true').lower() != 'false'+++def _intranet_host_allowlist():+ """Return a compiled regex matching admin-allowlisted intranet hosts.++ Off by default: the env var is empty so the regex matches nothing,+ meaning private IPs are blocked. Operators who genuinely want to+ POST to internal services set ``WEBHOOK_INTRANET_HOST_ALLOWLIST`` to+ a regex like ``^(home\\.lan|192\\.168\\.1\\.\\d+)$``.+ """+ raw = os.environ.get('WEBHOOK_INTRANET_HOST_ALLOWLIST', '')+ if not raw:+ return None+ try:+ return re.compile(raw)+ except re.error as e:+ logger.warning(f"Invalid WEBHOOK_INTRANET_HOST_ALLOWLIST regex {raw!r}: {e}")+ return None+++# Retry delays in seconds for attempts 1, 2, 3, 4, 5+.+_RETRY_DELAYS = [0, 30, 120, 600, 3600]+++def _delay_for_attempt(attempt_count: int) -> int:+ """Return the delay (seconds) BEFORE this attempt. attempt_count is+ 1-indexed: 1 = first attempt (immediate)."""+ if attempt_count <= 0:+ return 0+ if attempt_count - 1 < len(_RETRY_DELAYS):+ return _RETRY_DELAYS[attempt_count - 1]+ return _RETRY_DELAYS[-1]+++# ---- URL safety / SSRF guard ----------------------------------------------++def is_url_safe_for_webhook(url: str, allow_http: bool = False) -> tuple:+ """Validate a webhook URL.++ Returns ``(ok: bool, reason: str)``. ``ok`` is False when the URL+ points at a private/loopback/link-local IP (unless the+ ``WEBHOOK_INTRANET_HOST_ALLOWLIST`` regex matches the hostname), or+ uses an unsupported scheme.+ """+ if not url:+ return False, 'URL is required'+ try:+ parsed = urlparse(url)+ except Exception:+ return False, 'URL could not be parsed'++ scheme = (parsed.scheme or '').lower()+ if scheme not in ('http', 'https'):+ return False, 'Scheme must be http or https'+ if scheme == 'http' and not allow_http:+ return False, 'http:// URLs require allow_http=true'++ host = parsed.hostname+ if not host:+ return False, 'URL is missing a host'++ # Resolve host to all addresses; reject if any of them is a+ # private/loopback/link-local IP and the host is not in the admin+ # allowlist.+ allowlist = _intranet_host_allowlist()+ if allowlist and allowlist.search(host):+ return True, ''++ try:+ addrinfos = socket.getaddrinfo(host, None)+ except socket.gaierror:+ return False, f'DNS resolution failed for {host!r}'++ for af, _stype, _proto, _name, sockaddr in addrinfos:+ ip_str = sockaddr[0]+ try:+ ip = ipaddress.ip_address(ip_str)+ except ValueError:+ continue+ if ip.is_loopback or ip.is_private or ip.is_link_local or ip.is_reserved or ip.is_multicast:+ return False, (+ f'URL resolves to a private/loopback address ({ip_str}); set '+ 'WEBHOOK_INTRANET_HOST_ALLOWLIST to allow this host or use a public URL.'+ )++ return True, ''+++# ---- Signing & headers -----------------------------------------------------++def sign_payload(secret: str, body: bytes) -> str:+ """Compute the Speakr-Signature header value for ``body``."""+ mac = hmac.new(secret.encode('utf-8'), body, hashlib.sha256)+ return f'sha256={mac.hexdigest()}'+++def _build_envelope(event_id: str, event_type: str, user_id: int, data: dict):+ return {+ 'id': event_id,+ 'type': event_type,+ 'timestamp': datetime.utcnow().isoformat() + 'Z',+ 'user_id': user_id,+ 'data': data or {},+ }+++# ---- Public entry point: enqueue ------------------------------------------++def emit_webhook_event(user_id: int, event_type: str, data: dict, *, app=None) -> int:+ """Enqueue a webhook delivery for each subscribed endpoint.++ Returns the count of WebhookDelivery rows created (0 if no enabled+ webhooks are subscribed). Safe to call from request handlers; the+ actual HTTP POST happens off-request in the dispatcher loop.+ """+ if not _global_enabled():+ return 0+ if event_type not in WEBHOOK_EVENT_TYPES:+ logger.warning(f"emit_webhook_event called with unknown type {event_type!r}; dropping")+ return 0++ def _do_enqueue():+ # Find enabled, non-paused webhooks for the user that subscribe to this event.+ subscriptions = (+ Webhook.query+ .filter_by(user_id=user_id, enabled=True)+ .all()+ )+ matched = [w for w in subscriptions if event_type in w.event_list]+ if not matched:+ return 0++ event_id = str(uuid.uuid4())+ first_attempt_at = datetime.utcnow()+ created = 0+ for wh in matched:+ envelope = _build_envelope(event_id, event_type, user_id, data)+ delivery = WebhookDelivery(+ webhook_id=wh.id,+ event_id=event_id,+ event_type=event_type,+ payload=json.dumps(envelope),+ status='pending',+ next_retry_at=first_attempt_at,+ )+ db.session.add(delivery)+ created += 1+ if created:+ db.session.commit()+ return created++ if app is not None:+ with app.app_context():+ return _do_enqueue()+ return _do_enqueue()+++# ---- Dispatcher: one pass over due deliveries -----------------------------++def _post_delivery(delivery: WebhookDelivery, webhook: Webhook) -> tuple:+ """Run one HTTP attempt. Returns (response_status, body_preview, error).++ On network/timeout error, response_status is None and error is set.+ """+ body_bytes = (delivery.payload or '').encode('utf-8')+ signature = sign_payload(webhook.secret, body_bytes)+ headers = {+ 'Content-Type': 'application/json',+ 'User-Agent': f'Speakr-Webhook/1.0',+ 'Speakr-Signature': signature,+ 'Speakr-Delivery-Id': delivery.event_id,+ 'Speakr-Event': delivery.event_type,+ 'Speakr-Timestamp': datetime.utcnow().isoformat() + 'Z',+ }+ try:+ resp = requests.post(+ webhook.url,+ data=body_bytes,+ headers=headers,+ timeout=_delivery_timeout(),+ allow_redirects=False,+ )+ preview = (resp.text or '')[:2000]+ return resp.status_code, preview, None+ except requests.RequestException as e:+ return None, None, str(e)[:500]+++def _is_retryable_status(status_code) -> bool:+ if status_code is None:+ return True # network error+ if 200 <= status_code < 300:+ return False+ if status_code in (408, 429):+ return True+ if 500 <= status_code < 600:+ return True+ # 3xx redirects (we disabled allow_redirects), 4xx others = permanent+ return False+++def _apply_attempt_result(delivery: WebhookDelivery, status_code, body_preview, error):+ """Mutate the delivery row based on the HTTP outcome. Returns the+ new status string."""+ delivery.attempt_count = (delivery.attempt_count or 0) + 1+ delivery.response_status = status_code+ delivery.response_body_preview = body_preview+ delivery.error_message = error++ if status_code is not None and 200 <= status_code < 300:+ delivery.status = 'success'+ delivery.delivered_at = datetime.utcnow()+ delivery.next_retry_at = None+ return 'success'++ if not _is_retryable_status(status_code) or delivery.attempt_count >= _max_attempts():+ delivery.status = 'permanent_failure'+ delivery.next_retry_at = None+ return 'permanent_failure'++ delivery.status = 'failed'+ delay = _delay_for_attempt(delivery.attempt_count + 1)+ delivery.next_retry_at = datetime.utcnow() + timedelta(seconds=delay)+ return 'failed'+++def _due_deliveries(now: datetime, limit: int = 100):+ """Find deliveries that should be attempted now: pending OR failed+ with elapsed next_retry_at."""+ return (+ WebhookDelivery.query+ .filter(+ WebhookDelivery.status.in_(('pending', 'failed')),+ (WebhookDelivery.next_retry_at == None) | (WebhookDelivery.next_retry_at <= now), # noqa: E711+ )+ .order_by(WebhookDelivery.created_at.asc())+ .limit(limit)+ .all()+ )+++def run_dispatcher_pass(app=None, limit: int = 100) -> dict:+ """Run one sweep of the dispatcher. Returns a counters dict.++ Safe to call from tests; for production use, the background thread+ started in startup.py invokes this on a fixed interval.+ """+ if not _global_enabled():+ return {'attempted': 0, 'success': 0, 'failed': 0, 'permanent_failure': 0}++ def _run_one():+ now = datetime.utcnow()+ due = _due_deliveries(now, limit=limit)+ attempted = 0+ outcomes = {'success': 0, 'failed': 0, 'permanent_failure': 0}+ autopause_thresh = _autopause_failures()+ for delivery in due:+ webhook = delivery.webhook+ if webhook is None or not webhook.enabled:+ # Parent disabled while we were queued. Mark permanent so+ # we stop re-evaluating this row.+ delivery.status = 'permanent_failure'+ delivery.next_retry_at = None+ continue+ status_code, body_preview, error = _post_delivery(delivery, webhook)+ outcome = _apply_attempt_result(delivery, status_code, body_preview, error)+ attempted += 1+ outcomes[outcome] = outcomes.get(outcome, 0) + 1++ # Update the parent webhook's health counters.+ webhook.last_delivery_at = datetime.utcnow()+ if outcome == 'success':+ webhook.consecutive_failures = 0+ webhook.auto_paused = False+ else:+ if outcome == 'permanent_failure':+ webhook.consecutive_failures = (webhook.consecutive_failures or 0) + 1+ if webhook.consecutive_failures >= autopause_thresh:+ webhook.enabled = False+ webhook.auto_paused = True++ if attempted:+ db.session.commit()+ return {'attempted': attempted, **outcomes}++ if app is not None:+ with app.app_context():+ return _run_one()+ return _run_one()+++# ---- Background dispatcher thread -----------------------------------------++_dispatcher_thread_started = False+_dispatcher_thread_lock = threading.Lock()+++def start_dispatcher_thread(app):+ """Spawn the daemon dispatcher thread (idempotent)."""+ global _dispatcher_thread_started+ with _dispatcher_thread_lock:+ if _dispatcher_thread_started:+ return+ interval = _dispatcher_interval()++ def _loop():+ app.logger.info(f"Webhook dispatcher started (interval={interval}s)")+ while True:+ try:+ time.sleep(interval)+ if not _global_enabled():+ continue+ counters = run_dispatcher_pass(app=app)+ if counters.get('attempted'):+ app.logger.info(+ f"Webhook dispatcher pass: attempted={counters['attempted']} "+ f"success={counters.get('success', 0)} "+ f"failed={counters.get('failed', 0)} "+ f"permanent_failure={counters.get('permanent_failure', 0)}"+ )+ except Exception as e:+ app.logger.error(f"Webhook dispatcher error: {e}", exc_info=True)+ time.sleep(min(60, interval * 2))++ t = threading.Thread(target=_loop, daemon=True, name="WebhookDispatcher")+ t.start()+ _dispatcher_thread_started = True+ app.logger.info("✅ Webhook dispatcher thread initialized")diff --git a/tests/test_webhooks.py b/tests/test_webhooks.pynew file mode 100644index 00000000..6bc6d4dc--- /dev/null+++ b/tests/test_webhooks.py@@ -0,0 +1,546 @@+"""Webhook backend tests (#275).++Covers:++- model serialization + event_list validation+- HMAC signature generation+- SSRF guard (private IP block + intranet allowlist)+- emit_webhook_event creates delivery rows for matching subscriptions+- dispatcher pass: success path, retry-with-backoff path, permanent+ failure path, auto-pause after N consecutive failures+- v1 CRUD endpoints: create/list/get/patch/delete/test/rotate-secret+- replay creates a new delivery with a fresh event_id+"""++import hashlib+import hmac+import json+import os+import sys+import uuid+from datetime import datetime, timedelta+from unittest.mock import patch, MagicMock++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from src.app import app, db+from src.models import User, Webhook, WebhookDelivery, WEBHOOK_EVENT_TYPES, generate_webhook_secret+from src.services.webhook_dispatch import (+ sign_payload,+ is_url_safe_for_webhook,+ emit_webhook_event,+ run_dispatcher_pass,+ _delay_for_attempt,+)+++app.config["WTF_CSRF_ENABLED"] = False+++def _make_user(prefix):+ suffix = uuid.uuid4().hex[:8]+ user = User(+ username=f"{prefix}_{suffix}",+ email=f"{prefix}_{suffix}@local.test",+ password="x",+ )+ db.session.add(user)+ db.session.commit()+ return user+++def _login(client, user):+ from flask import g+ with client.session_transaction() as sess:+ sess.clear()+ sess["_user_id"] = str(user.id)+ sess["_fresh"] = True+ try:+ g.pop("_login_user", None)+ except RuntimeError:+ pass+++# --- Model tests -----------------------------------------------------------++def test_event_list_setter_dedupes_and_validates():+ with app.app_context():+ user = _make_user("wh_model")+ wh = Webhook(user_id=user.id, name="t", url="https://example.com/x")+ wh.event_list = ['recording.created', 'recording.created', 'recording.deleted']+ assert wh.event_list == ['recording.created', 'recording.deleted']+ try:+ wh.event_list = ['not.a.real.event']+ assert False, "expected ValueError"+ except ValueError:+ pass+ db.session.delete(user)+ db.session.commit()+++def test_generate_webhook_secret_returns_distinct_values():+ a = generate_webhook_secret()+ b = generate_webhook_secret()+ assert a and b and a != b+ assert len(a) >= 32+++def test_to_dict_omits_secret_by_default():+ with app.app_context():+ user = _make_user("wh_secret")+ wh = Webhook(user_id=user.id, name="t", url="https://example.com/x", secret="topsecret")+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()+ assert 'secret' not in wh.to_dict()+ assert wh.to_dict(include_secret=True)['secret'] == 'topsecret'+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++# --- Signature ---------------------------------------------------------------++def test_sign_payload_matches_hmac_sha256():+ body = b'{"hello":"world"}'+ secret = 'shared-secret'+ sig = sign_payload(secret, body)+ expected_hex = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()+ assert sig == f'sha256={expected_hex}'+++# --- SSRF guard --------------------------------------------------------------++def test_is_url_safe_rejects_http_when_allow_http_false():+ ok, reason = is_url_safe_for_webhook('http://example.com/wh', allow_http=False)+ assert not ok+ assert 'http' in reason.lower()+++def test_is_url_safe_accepts_https_public():+ ok, _ = is_url_safe_for_webhook('https://example.com/wh', allow_http=False)+ assert ok+++def test_is_url_safe_rejects_private_ip():+ # 192.168.0.0/16 is RFC1918; should be rejected by default.+ ok, reason = is_url_safe_for_webhook('http://192.168.1.50/x', allow_http=True)+ assert not ok+ assert 'private' in reason.lower() or 'loopback' in reason.lower()+++def test_is_url_safe_rejects_loopback():+ ok, reason = is_url_safe_for_webhook('http://127.0.0.1/x', allow_http=True)+ assert not ok+++def test_is_url_safe_allowlist_overrides_private_ip():+ # Set the env var so 192.168.1.50 is allowed.+ with patch.dict(os.environ, {'WEBHOOK_INTRANET_HOST_ALLOWLIST': r'^192\.168\.1\.\d+$'}):+ ok, _ = is_url_safe_for_webhook('http://192.168.1.50/x', allow_http=True)+ assert ok+++# --- emit_webhook_event ------------------------------------------------------++def test_emit_creates_delivery_row_for_matching_subscription():+ with app.app_context():+ user = _make_user("wh_emit")+ wh = Webhook(user_id=user.id, name="t", url="https://example.com/wh", enabled=True)+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()++ created = emit_webhook_event(user.id, 'recording.created', {'recording_id': 42})+ assert created == 1++ deliveries = WebhookDelivery.query.filter_by(webhook_id=wh.id).all()+ assert len(deliveries) == 1+ d = deliveries[0]+ assert d.status == 'pending'+ envelope = json.loads(d.payload)+ assert envelope['type'] == 'recording.created'+ assert envelope['user_id'] == user.id+ assert envelope['data']['recording_id'] == 42++ # Cleanup+ for d in deliveries:+ db.session.delete(d)+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_emit_skips_unsubscribed_event():+ with app.app_context():+ user = _make_user("wh_unsub")+ wh = Webhook(user_id=user.id, name="t", url="https://example.com/wh", enabled=True)+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()++ created = emit_webhook_event(user.id, 'recording.deleted', {'recording_id': 1})+ assert created == 0+ assert WebhookDelivery.query.filter_by(webhook_id=wh.id).count() == 0++ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_emit_skips_disabled_webhook():+ with app.app_context():+ user = _make_user("wh_disabled")+ wh = Webhook(user_id=user.id, name="t", url="https://example.com/wh", enabled=False)+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()+ created = emit_webhook_event(user.id, 'recording.created', {})+ assert created == 0+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++# --- Dispatcher pass --------------------------------------------------------++def _seed_pending(user_id, *, url='https://example.com/wh', secret='s'):+ wh = Webhook(user_id=user_id, name="t", url=url, secret=secret, enabled=True)+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.flush()+ d = WebhookDelivery(+ webhook_id=wh.id,+ event_id=str(uuid.uuid4()),+ event_type='recording.created',+ payload=json.dumps({'id': 'x', 'type': 'recording.created', 'data': {}}),+ status='pending',+ next_retry_at=datetime.utcnow(),+ )+ db.session.add(d)+ db.session.commit()+ return wh, d+++def test_dispatcher_success_path_marks_delivered():+ with app.app_context():+ user = _make_user("wh_disp_ok")+ wh, d = _seed_pending(user.id)++ mock_resp = MagicMock(status_code=204, text='')+ with patch('src.services.webhook_dispatch.requests.post', return_value=mock_resp) as post:+ counters = run_dispatcher_pass()+ assert counters['attempted'] == 1+ assert counters['success'] == 1+ post.assert_called_once()+ call = post.call_args+ # Signature header is set+ headers = call.kwargs['headers']+ assert headers['Speakr-Signature'].startswith('sha256=')+ assert headers['Speakr-Event'] == 'recording.created'++ d_refreshed = db.session.get(WebhookDelivery, d.id)+ wh_refreshed = db.session.get(Webhook, wh.id)+ assert d_refreshed.status == 'success'+ assert d_refreshed.attempt_count == 1+ assert wh_refreshed.consecutive_failures == 0++ db.session.delete(d_refreshed)+ db.session.delete(wh_refreshed)+ db.session.delete(user)+ db.session.commit()+++def test_dispatcher_retryable_failure_marks_failed_with_backoff():+ with app.app_context():+ user = _make_user("wh_disp_retry")+ wh, d = _seed_pending(user.id)++ mock_resp = MagicMock(status_code=502, text='bad gateway')+ with patch('src.services.webhook_dispatch.requests.post', return_value=mock_resp):+ counters = run_dispatcher_pass()+ assert counters['attempted'] == 1+ assert counters['failed'] == 1++ d_refreshed = db.session.get(WebhookDelivery, d.id)+ assert d_refreshed.status == 'failed'+ assert d_refreshed.attempt_count == 1+ assert d_refreshed.next_retry_at is not None+ assert d_refreshed.next_retry_at > datetime.utcnow()++ db.session.delete(d_refreshed)+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_dispatcher_permanent_failure_on_4xx():+ with app.app_context():+ user = _make_user("wh_disp_perm")+ wh, d = _seed_pending(user.id)++ mock_resp = MagicMock(status_code=400, text='bad request')+ with patch('src.services.webhook_dispatch.requests.post', return_value=mock_resp):+ counters = run_dispatcher_pass()+ assert counters['permanent_failure'] == 1++ d_refreshed = db.session.get(WebhookDelivery, d.id)+ assert d_refreshed.status == 'permanent_failure'+ wh_refreshed = db.session.get(Webhook, wh.id)+ assert wh_refreshed.consecutive_failures == 1++ db.session.delete(d_refreshed)+ db.session.delete(wh_refreshed)+ db.session.delete(user)+ db.session.commit()+++def test_dispatcher_autopauses_after_threshold():+ with app.app_context():+ user = _make_user("wh_autopause")+ wh, _ = _seed_pending(user.id)+ # Pretend 9 consecutive failures already happened; threshold is 10.+ wh.consecutive_failures = 9+ db.session.commit()++ # The seeded delivery is permanent-failed → 10th consecutive failure+ # should auto-pause.+ mock_resp = MagicMock(status_code=410, text='gone') # 4xx permanent+ with patch.dict(os.environ, {'WEBHOOK_AUTOPAUSE_FAILURES': '10'}):+ with patch('src.services.webhook_dispatch.requests.post', return_value=mock_resp):+ run_dispatcher_pass()++ wh_refreshed = db.session.get(Webhook, wh.id)+ assert wh_refreshed.enabled is False+ assert wh_refreshed.auto_paused is True+ assert wh_refreshed.consecutive_failures == 10++ for d in WebhookDelivery.query.filter_by(webhook_id=wh.id).all():+ db.session.delete(d)+ db.session.delete(wh_refreshed)+ db.session.delete(user)+ db.session.commit()+++def test_delay_for_attempt_uses_designed_schedule():+ # Attempt 1 = immediate (0s), then 30s, 120s, 600s, 3600s, then 3600 cap.+ assert _delay_for_attempt(1) == 0+ assert _delay_for_attempt(2) == 30+ assert _delay_for_attempt(3) == 120+ assert _delay_for_attempt(4) == 600+ assert _delay_for_attempt(5) == 3600+ assert _delay_for_attempt(99) == 3600+++# --- v1 CRUD endpoints ------------------------------------------------------++def test_create_webhook_returns_secret_once_and_omits_thereafter():+ with app.app_context():+ user = _make_user("wh_crud_create")+ client = app.test_client()+ _login(client, user)+ resp = client.post('/api/v1/webhooks', json={+ 'name': 'n8n prod',+ 'url': 'https://example.com/hook',+ 'events': ['recording.created', 'recording.transcription.completed'],+ })+ assert resp.status_code == 201, resp.data+ body = resp.get_json()+ assert 'secret' in body and len(body['secret']) > 0+ wh_id = body['id']++ # Subsequent reads omit secret+ get_resp = client.get(f'/api/v1/webhooks/{wh_id}')+ assert get_resp.status_code == 200+ assert 'secret' not in get_resp.get_json()++ # Cleanup+ client.delete(f'/api/v1/webhooks/{wh_id}')+ db.session.delete(user)+ db.session.commit()+++def test_create_webhook_rejects_unknown_event():+ with app.app_context():+ user = _make_user("wh_crud_unknown")+ client = app.test_client()+ _login(client, user)+ resp = client.post('/api/v1/webhooks', json={+ 'name': 'x', 'url': 'https://e.com/h', 'events': ['nope.bad'],+ })+ assert resp.status_code == 400+ db.session.delete(user)+ db.session.commit()+++def test_create_webhook_rejects_private_url():+ with app.app_context():+ user = _make_user("wh_crud_private")+ client = app.test_client()+ _login(client, user)+ resp = client.post('/api/v1/webhooks', json={+ 'name': 'x', 'url': 'http://192.168.0.5/h', 'allow_http': True,+ 'events': ['recording.created'],+ })+ assert resp.status_code == 400+ db.session.delete(user)+ db.session.commit()+++def test_list_only_returns_caller_webhooks():+ with app.app_context():+ a = _make_user("wh_list_a")+ b = _make_user("wh_list_b")+ wh_a = Webhook(user_id=a.id, name='A', url='https://example.com/a')+ wh_a.event_list = ['recording.created']+ wh_b = Webhook(user_id=b.id, name='B', url='https://example.com/b')+ wh_b.event_list = ['recording.created']+ db.session.add_all([wh_a, wh_b])+ db.session.commit()++ client = app.test_client()+ _login(client, a)+ resp = client.get('/api/v1/webhooks')+ body = resp.get_json()+ ids = [w['id'] for w in body['webhooks']]+ assert wh_a.id in ids+ assert wh_b.id not in ids++ db.session.delete(wh_a); db.session.delete(wh_b)+ db.session.delete(a); db.session.delete(b)+ db.session.commit()+++def test_patch_webhook_updates_events_and_enabled():+ with app.app_context():+ user = _make_user("wh_crud_patch")+ client = app.test_client()+ _login(client, user)+ wh = Webhook(user_id=user.id, name='x', url='https://example.com/h')+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()++ resp = client.patch(f'/api/v1/webhooks/{wh.id}', json={+ 'events': ['recording.summary.completed'],+ 'enabled': False,+ })+ assert resp.status_code == 200+ body = resp.get_json()+ assert body['events'] == ['recording.summary.completed']+ assert body['enabled'] is False++ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_rotate_secret_returns_fresh_secret():+ with app.app_context():+ user = _make_user("wh_crud_rotate")+ client = app.test_client()+ _login(client, user)+ wh = Webhook(user_id=user.id, name='x', url='https://example.com/h', secret='old-secret')+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()+ old = wh.secret+ resp = client.post(f'/api/v1/webhooks/{wh.id}/rotate-secret')+ assert resp.status_code == 200+ body = resp.get_json()+ assert body['secret'] != old+ wh_refreshed = db.session.get(Webhook, wh.id)+ assert wh_refreshed.secret == body['secret']+ db.session.delete(wh_refreshed)+ db.session.delete(user)+ db.session.commit()+++def test_test_fire_enqueues_synthetic_delivery():+ with app.app_context():+ user = _make_user("wh_crud_test")+ client = app.test_client()+ _login(client, user)+ wh = Webhook(user_id=user.id, name='x', url='https://example.com/h', enabled=True)+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.commit()+ resp = client.post(f'/api/v1/webhooks/{wh.id}/test')+ assert resp.status_code == 202+ d_id = resp.get_json()['id']+ d = db.session.get(WebhookDelivery, d_id)+ assert d.event_type == 'webhook.test'+ assert d.status == 'pending'+ db.session.delete(d)+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_replay_creates_new_delivery_with_fresh_event_id():+ with app.app_context():+ user = _make_user("wh_crud_replay")+ client = app.test_client()+ _login(client, user)+ wh = Webhook(user_id=user.id, name='x', url='https://example.com/h')+ wh.event_list = ['recording.created']+ db.session.add(wh)+ db.session.flush()+ original = WebhookDelivery(+ webhook_id=wh.id,+ event_id=str(uuid.uuid4()),+ event_type='recording.created',+ payload=json.dumps({'id': 'orig', 'type': 'recording.created', 'data': {'r': 1}}),+ status='permanent_failure',+ )+ db.session.add(original)+ db.session.commit()++ resp = client.post(f'/api/v1/webhooks/{wh.id}/deliveries/{original.id}/replay')+ assert resp.status_code == 202+ replay_id = resp.get_json()['id']+ replay = db.session.get(WebhookDelivery, replay_id)+ assert replay.id != original.id+ assert replay.event_id != original.event_id+ assert replay.status == 'pending'+ env = json.loads(replay.payload)+ assert env['replayed_from'] == original.event_id++ db.session.delete(replay)+ db.session.delete(original)+ db.session.delete(wh)+ db.session.delete(user)+ db.session.commit()+++def test_per_user_cap_enforced():+ with app.app_context():+ user = _make_user("wh_crud_cap")+ client = app.test_client()+ _login(client, user)+ with patch.dict(os.environ, {'WEBHOOK_MAX_PER_USER': '2'}):+ for i in range(2):+ r = client.post('/api/v1/webhooks', json={+ 'name': f'h{i}', 'url': f'https://example.com/{i}',+ 'events': ['recording.created'],+ })+ assert r.status_code == 201, r.data+ r = client.post('/api/v1/webhooks', json={+ 'name': 'too-many', 'url': 'https://example.com/x',+ 'events': ['recording.created'],+ })+ assert r.status_code == 409++ for w in Webhook.query.filter_by(user_id=user.id).all():+ db.session.delete(w)+ db.session.delete(user)+ db.session.commit()+++def teardown_module(module):+ with app.app_context():+ for u in User.query.filter(User.username.like("wh_%")).all():+ for w in Webhook.query.filter_by(user_id=u.id).all():+ db.session.delete(w)+ db.session.delete(u)+ db.session.commit()