fix(automation): register automation task in celery worker and add docs

- Import deliver_automation_hook_task in celery_worker.py
- Add Automation (Zapier / Make.com) section to docs/API.md
- Add AUTOMATION_HOOKS_ENABLED to docs/ConfigurationGuide.md

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

app/celery_worker.py

@@ -10,6 +10,7 @@ from app import tasks  # noqa: F401 - Imports app/tasks.py so Celery can registe
 # Import the shared Celery instance
 from app.celery_app import celery
 from app.config import settings
+from app.tasks.automation_tasks import deliver_automation_hook_task  # noqa: F401
 from app.tasks.backup_tasks import cleanup_old_backups, create_backup  # noqa: F401
 from app.tasks.batch_tasks import (  # noqa: F401
     backfill_missing_metadata,

docs/API.md

@@ -2060,6 +2060,158 @@ print(response.json())
 ```
 
 
+## Automation (Zapier / Make.com)
+
+Manage automation hook subscriptions for integrating DocuElevate with external platforms like Zapier and Make.com. All endpoints require API token authentication (`Authorization: Bearer <token>`).
+
+### Supported Events
+
+The automation system shares event types with the [Webhooks](#webhooks) subsystem:
+
+| Event | Description |
+|-------|-------------|
+| `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/automation/events
+
+List all valid event types that automation hooks can subscribe to.
+
+**Response (200):**
+```json
+["document.failed", "document.processed", "document.uploaded", "user.payment_issue", "user.plan_changed", "user.signup"]
+```
+
+### POST /api/automation/hooks/subscribe
+
+Subscribe to DocuElevate events. Zapier and Make.com call this endpoint to register a webhook URL that receives event notifications.
+
+**Request:**
+```bash
+curl -X POST "http://your-instance/api/automation/hooks/subscribe" \
+  -H "Authorization: Bearer de_your_token_here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
+    "events": ["document.processed", "document.uploaded"],
+    "hook_type": "zapier",
+    "secret": "optional-signing-secret",
+    "description": "My Zap for processed documents"
+  }'
+```
+
+**Response (201):**
+```json
+{
+  "id": 1,
+  "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
+  "events": ["document.processed", "document.uploaded"],
+  "is_active": true,
+  "hook_type": "zapier",
+  "description": "My Zap for processed documents",
+  "has_secret": true
+}
+```
+
+### GET /api/automation/hooks
+
+List all automation hook subscriptions.
+
+**Response (200):**
+```json
+[
+  {
+    "id": 1,
+    "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
+    "events": ["document.processed", "document.uploaded"],
+    "is_active": true,
+    "hook_type": "zapier",
+    "description": "My Zap for processed documents",
+    "has_secret": true
+  }
+]
+```
+
+### DELETE /api/automation/hooks/{hook_id}
+
+Unsubscribe an automation hook. Zapier calls this when a Zap is turned off or deleted.
+
+**Response (204):** No content.
+
+### GET /api/automation/triggers/sample/{event}
+
+Get sample trigger data for Zapier field mapping. Zapier uses this during Zap setup to discover available fields.
+
+**Request:**
+```bash
+curl "http://your-instance/api/automation/triggers/sample/document.processed" \
+  -H "Authorization: Bearer de_your_token_here"
+```
+
+**Response (200):**
+```json
+[
+  {
+    "id": "evt_sample0002",
+    "event": "document.processed",
+    "timestamp": 1710000060.0,
+    "document_id": 42,
+    "filename": "invoice_2024.pdf",
+    "status": "processed",
+    "title": "Invoice #1234",
+    "owner_id": "user@example.com"
+  }
+]
+```
+
+### POST /api/automation/actions/upload
+
+Upload a document from an automation platform. This incoming action endpoint allows Zapier or Make.com to push documents into DocuElevate for processing.
+
+**Request:**
+```bash
+curl -X POST "http://your-instance/api/automation/actions/upload" \
+  -H "Authorization: Bearer de_your_token_here" \
+  -F "file=@/path/to/document.pdf"
+```
+
+**Response (200):**
+```json
+{
+  "status": "accepted",
+  "filename": "document.pdf",
+  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+}
+```
+
+### Zapier-Compatible Payload Format
+
+When events fire, automation hooks receive a **flat JSON payload** (no nested `data` key) that Zapier and Make.com can easily map:
+
+```json
+{
+  "id": "evt_a1b2c3d4e5f67890",
+  "event": "document.processed",
+  "timestamp": 1710000060.0,
+  "document_id": 42,
+  "filename": "invoice_2024.pdf",
+  "status": "processed",
+  "title": "Invoice #1234",
+  "owner_id": "user@example.com"
+}
+```
+
+The `id` field is unique per event and is used by Zapier for deduplication. If a `secret` was provided during subscription, an `X-Webhook-Signature` header with an HMAC-SHA256 signature is included.
+
+### Retry Behavior
+
+Automation hook deliveries follow the same retry policy as regular webhooks: up to 3 retries with exponential backoff (60 s, 300 s, 900 s) and ±20% jitter.
+
+
 ## Further Assistance
 
 For additional help with the API, please contact our support team or refer to the [Development Guide](../CONTRIBUTING.md).

docs/ConfigurationGuide.md

@@ -1144,6 +1144,26 @@ Configurations are stored in the database and managed through the API (see [API
 
 Webhook URLs, secrets, and subscribed events are configured per-webhook via the `/api/webhooks/` endpoints (admin access required). Each delivery includes an optional HMAC-SHA256 signature for verification and is retried with exponential backoff on failure.
 
+### Automation Hooks (Zapier / Make.com)
+
+Automation hooks enable integration with external automation platforms such as
+[Zapier](https://zapier.com) and [Make.com](https://make.com) (formerly Integromat).
+
+| **Variable**               | **Description**                                                                                | **Default** |
+|----------------------------|------------------------------------------------------------------------------------------------|-------------|
+| `AUTOMATION_HOOKS_ENABLED` | Enable or disable Zapier / Make.com automation hook subscriptions and delivery (`True`/`False`) | `True`      |
+
+When enabled, external platforms can:
+
+- **Subscribe** to DocuElevate events via `POST /api/automation/hooks/subscribe` (outgoing triggers)
+- **Send documents** to DocuElevate via `POST /api/automation/actions/upload` (incoming actions)
+- **Discover fields** via `GET /api/automation/triggers/sample/{event}` (Zapier field mapping)
+
+Automation hooks share the same event types as webhooks (`document.uploaded`, `document.processed`,
+`document.failed`, `user.signup`, `user.plan_changed`, `user.payment_issue`) and use a flat
+Zapier-compatible JSON payload format.  See the [API docs](API.md#automation-zapier--makecom) for
+endpoint details and payload examples.
+
 ### Backup & Restore
 
 DocuElevate automatically backs up the database on a scheduled basis.