Skip to content

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.py
index 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.py
new file mode 100644
index 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()), 202
diff --git a/src/app.py b/src/app.py
index 6915e258..54cd7017 100644
--- a/src/app.py
+++ b/src/app.py
@@ -625,6 +625,7 @@ from src.api.system import system_bp, init_system_helpers
from src.api.push_notifications import push_bp
from src.api.api_v1 import api_v1_bp, init_api_v1_helpers
from 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_required
diff --git a/src/config/startup.py b/src/config/startup.py
index 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__.py
index 8d23e6c0..3ed3e257 100644
--- a/src/models/__init__.py
+++ b/src/models/__init__.py
@@ -32,6 +32,13 @@ from .processing_job import ProcessingJob
from .recording_session import RecordingSession, RECORDING_SESSION_STATUSES
from .token_usage import TokenUsage
from .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.py
new file mode 100644
index 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.py
index 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 instance
job_queue = FairJobQueue()
diff --git a/src/services/webhook_dispatch.py b/src/services/webhook_dispatch.py
new file mode 100644
index 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.py
new file mode 100644
index 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()