Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""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.utils.token_auth import require_scope
from src.database import db
from src.models import Webhook, WebhookDelivery, WEBHOOK_EVENT_TYPES, generate_webhook_secret
from src.utils.localization import api_error
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(api_error('webhook_not_found')), 404)
return wh, None
# ---- Collection ------------------------------------------------------------
@webhooks_bp.route('', methods=['GET'])
@require_scope('webhooks')
@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'])
@require_scope('webhooks')
@login_required
def create_webhook():
"""Create a webhook.
Body: ``{name, url, events, allow_http=false, enabled=true, include_shared=false}``.
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(api_error('name_required')), 400
if not url:
return jsonify(api_error('url_required')), 400
if not isinstance(events, list) or not events:
return jsonify(api_error('invalid_events_list')), 400
unknown = [e for e in events if e not in WEBHOOK_EVENT_TYPES]
if unknown:
return jsonify({
**api_error('unknown_event_types', events=', '.join(str(e) for e in 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({
**api_error('webhook_cap_reached', count=existing, max=_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,
include_shared=bool(data.get('include_shared', False)),
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'])
@require_scope('webhooks')
@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'])
@require_scope('webhooks')
@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(api_error('name_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(api_error('invalid_events_list')), 400
try:
wh.event_list = events
except ValueError as e:
return jsonify({'error': str(e)}), 400
if 'include_shared' in data:
wh.include_shared = bool(data.get('include_shared'))
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'])
@require_scope('webhooks')
@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'])
@require_scope('webhooks')
@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
# The old secret stays valid for WEBHOOK_SECRET_GRACE_HOURS: Speakr-Signature-V2
# carries a second v1= value signed with it until then (spec W2).
import os as _os
from datetime import timedelta
try:
grace_hours = float(_os.environ.get('WEBHOOK_SECRET_GRACE_HOURS', '24'))
except ValueError:
grace_hours = 24.0
if grace_hours > 0:
wh.previous_secret = wh.secret
wh.previous_secret_expires_at = datetime.utcnow() + timedelta(hours=grace_hours)
else:
wh.previous_secret = None
wh.previous_secret_expires_at = None
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'])
@require_scope('webhooks')
@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(api_error('webhook_disabled')), 409
import uuid
from src.services.webhook_dispatch import _build_envelope, serialize_envelope
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=serialize_envelope(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'])
@require_scope('webhooks')
@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'])
@require_scope('webhooks')
@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(api_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'])
@require_scope('webhooks')
@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(api_error('delivery_not_found')), 404
import uuid
import json as _json
from src.services.webhook_dispatch import serialize_envelope
new_event_id = str(uuid.uuid4())
# Update the envelope's id field so the receiver sees a fresh delivery id.
try:
envelope = _json.loads(src.payload)
envelope['id'] = new_event_id
envelope['timestamp'] = datetime.utcnow().isoformat() + 'Z'
envelope['occurred_at'] = envelope['timestamp']
envelope['replayed_from'] = src.event_id
new_payload = serialize_envelope(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