feat(notifications): admin push notifications and webhooks for user signup, plan changes, and payment issues

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

app/utils/notification.py

@@ -204,3 +204,104 @@ The file has been successfully processed and is being uploaded to all configured
     return send_notification(
         title=title, message=message.strip(), notification_type="success", tags=["document", "processed", "success"]
     )
+
+
+def notify_user_signup(user_id: str, display_name: str | None = None, email: str | None = None) -> bool:
+    """Send a notification to admins when a new user signs up.
+
+    Args:
+        user_id: The stable user identifier (preferred_username / email / sub).
+        display_name: Optional human-readable name for the user.
+        email: Optional email address for the user.
+
+    Returns:
+        bool: True if the notification was sent successfully.
+    """
+    if not settings.notify_on_user_signup:
+        return False
+
+    name_str = display_name or user_id
+    email_str = email or "N/A"
+
+    title = f"New User Signup: {name_str}"
+    message = f"""A new user has signed up for DocuElevate.
+
+User ID: {user_id}
+Display Name: {name_str}
+Email: {email_str}
+
+Review the new account in the admin panel."""
+
+    return send_notification(
+        title=title,
+        message=message.strip(),
+        notification_type="info",
+        tags=["user", "signup"],
+    )
+
+
+def notify_plan_changed(
+    user_id: str,
+    old_tier: str,
+    new_tier: str,
+    changed_by: str = "user",
+) -> bool:
+    """Send a notification to admins when a user changes their subscription plan.
+
+    Args:
+        user_id: The stable user identifier.
+        old_tier: The previous subscription tier.
+        new_tier: The new subscription tier.
+        changed_by: Who initiated the change (``"user"`` or ``"admin"``).
+
+    Returns:
+        bool: True if the notification was sent successfully.
+    """
+    if not settings.notify_on_plan_change:
+        return False
+
+    title = f"Plan Changed: {user_id}"
+    message = f"""A user's subscription plan has changed.
+
+User ID: {user_id}
+Previous Plan: {old_tier}
+New Plan: {new_tier}
+Changed By: {changed_by}
+
+Review the account in the admin panel."""
+
+    return send_notification(
+        title=title,
+        message=message.strip(),
+        notification_type="info",
+        tags=["user", "plan", "subscription"],
+    )
+
+
+def notify_payment_issue(user_id: str, issue: str) -> bool:
+    """Send a notification to admins when a payment issue is reported for a user.
+
+    Args:
+        user_id: The stable user identifier.
+        issue: A human-readable description of the payment issue.
+
+    Returns:
+        bool: True if the notification was sent successfully.
+    """
+    if not settings.notify_on_payment_issue:
+        return False
+
+    title = f"Payment Issue: {user_id}"
+    message = f"""A payment issue has been reported for a user.
+
+User ID: {user_id}
+Issue: {issue}
+
+Please review the account in the admin panel and follow up with the user."""
+
+    return send_notification(
+        title=title,
+        message=message.strip(),
+        notification_type="warning",
+        tags=["user", "payment", "billing"],
+    )

app/utils/settings_service.py

@@ -1251,6 +1251,30 @@ SETTING_METADATA = {
         "required": False,
         "restart_required": False,
     },
+    "notify_on_user_signup": {
+        "category": "Notifications",
+        "description": "Send admin notifications when a new user signs up",
+        "type": "boolean",
+        "sensitive": False,
+        "required": False,
+        "restart_required": False,
+    },
+    "notify_on_plan_change": {
+        "category": "Notifications",
+        "description": "Send admin notifications when a user changes their subscription plan",
+        "type": "boolean",
+        "sensitive": False,
+        "required": False,
+        "restart_required": False,
+    },
+    "notify_on_payment_issue": {
+        "category": "Notifications",
+        "description": "Send admin notifications when a payment issue is reported for a user",
+        "type": "boolean",
+        "sensitive": False,
+        "required": False,
+        "restart_required": False,
+    },
     # Feature Flags
     "allow_file_delete": {
         "category": "Feature Flags",

app/utils/webhook.py

@@ -7,6 +7,9 @@ Supported events:
 - ``document.uploaded``  – a new document has been ingested
 - ``document.processed`` – a document finished processing successfully
 - ``document.failed``    – document processing failed
+- ``user.signup``        – a new user account was created
+- ``user.plan_changed``  – a user's subscription plan changed
+- ``user.payment_issue`` – a payment issue was reported for a user
 """
 
 import hashlib
@@ -29,6 +32,9 @@ VALID_EVENTS: frozenset[str] = frozenset(
         "document.uploaded",
         "document.processed",
         "document.failed",
+        "user.signup",
+        "user.plan_changed",
+        "user.payment_issue",
     }
 )