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>

docs/API.md

@@ -812,6 +812,38 @@ Returns `204 No Content` on success, `404` if no profile exists.
 
 ---
 
+**POST** `/api/admin/users/{user_id}/payment-issue`
+
+Report a payment issue for a user. Sends an admin notification (via configured Apprise channels) and
+fires a `user.payment_issue` webhook event.  Use this endpoint when a payment processor (e.g.
+Stripe, PayPal) sends a failed-charge notification or when a manual billing review identifies a
+problem.
+
+**Request body**:
+```json
+{
+  "issue": "Card declined: insufficient funds"
+}
+```
+
+- `issue` (required): Human-readable description of the payment problem (1–2048 characters)
+
+**Response (200)**:
+```json
+{
+  "acknowledged": true,
+  "user_id": "alice@example.com",
+  "profile": { ... }
+}
+```
+
+**Error Responses**:
+- `404`: User profile not found
+- `403`: Admin access required
+- `422`: Validation error (e.g. empty issue string)
+
+---
+
 ### Settings Suggestions (Autocomplete)
 
 **GET** `/api/settings/{key}/suggestions`
@@ -1072,6 +1104,9 @@ Manage webhook configurations for notifying external systems when document event
 | `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 |
 
 ### GET /api/webhooks/events/
 
@@ -1079,7 +1114,7 @@ List all valid webhook event types.
 
 **Response (200):**
 ```json
-["document.failed", "document.processed", "document.uploaded"]
+["document.failed", "document.processed", "document.uploaded", "user.payment_issue", "user.plan_changed", "user.signup"]
 ```
 
 ### GET /api/webhooks/

docs/ConfigurationGuide.md

@@ -853,6 +853,26 @@ For detailed setup instructions, see the [Amazon S3 Setup Guide](AmazonS3Setup.m
 | `NOTIFY_ON_CREDENTIAL_FAILURE` | Send notifications on credential failures (`True`/`False`) |
 | `NOTIFY_ON_STARTUP`        | Send notification when system starts (`True`/`False`)    |
 | `NOTIFY_ON_SHUTDOWN`       | Send notification when system shuts down (`True`/`False`)|
+| `NOTIFY_ON_FILE_PROCESSED` | Send notification when a file is successfully processed (`True`/`False`) |
+| `NOTIFY_ON_USER_SIGNUP`    | Send admin notification when a new user signs up (`True`/`False`, default `True`) |
+| `NOTIFY_ON_PLAN_CHANGE`    | Send admin notification when a user changes their subscription plan (`True`/`False`, default `True`) |
+| `NOTIFY_ON_PAYMENT_ISSUE`  | Send admin notification when a payment issue is reported for a user (`True`/`False`, default `True`) |
+
+#### User-Event Notifications
+
+DocuElevate sends admin push notifications (via Apprise) and fires outbound webhooks for three
+user-lifecycle events:
+
+| Event | Trigger | Notification type |
+|-------|---------|-------------------|
+| **New signup** | A first-time user logs in and a UserProfile is created | `NOTIFY_ON_USER_SIGNUP` |
+| **Plan change** | A user selects a new subscription tier during onboarding, or an admin changes their tier | `NOTIFY_ON_PLAN_CHANGE` |
+| **Payment issue** | An admin POSTs to `/api/admin/users/{user_id}/payment-issue` | `NOTIFY_ON_PAYMENT_ISSUE` |
+
+In addition to the Apprise push notification, each event also fires the matching webhook event
+(`user.signup`, `user.plan_changed`, `user.payment_issue`) to all active webhook configurations
+subscribed to that event, enabling integration with CRM, helpdesk (Jira, Zendesk, etc.), or
+payment processors.
 
 For detailed setup instructions, see the [Notifications Setup Guide](NotificationsSetup.md).