From ce2a76fb770da3257b31cb5958c888821a23da0c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 23:59:15 +0000 Subject: [PATCH] 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 | 1 + docs/API.md | 152 +++++++++++++++++++++++++++++++++++++ docs/ConfigurationGuide.md | 20 +++++ 3 files changed, 173 insertions(+) diff --git a/app/celery_worker.py b/app/celery_worker.py index 4881f8a9..ef077a93 100644 --- a/app/celery_worker.py +++ b/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, diff --git a/docs/API.md b/docs/API.md index d5a0bf40..9ae011d8 100644 --- a/docs/API.md +++ b/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 `). + +### 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). diff --git a/docs/ConfigurationGuide.md b/docs/ConfigurationGuide.md index 009dc5a9..b77415b2 100644 --- a/docs/ConfigurationGuide.md +++ b/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.