Feature: External Workflow Webhooks and Delivery Audit Trail

[hoangsonww]

Summary

Add a first-class outbound webhook and notification integration layer so DocuThinker can publish document lifecycle and AI analysis events to external systems such as Slack, Teams, automation tools, and internal services.

Problem / Opportunity

DocuThinker already has document upload, AI analysis, chat, RAG, and operational alerting concepts, but product-level document events are not exposed as configurable integrations. Users who want to trigger downstream review, archive, ticketing, or knowledge workflows must poll the API or manually copy results out of the app.

Proposed Feature

Introduce user-configurable webhook subscriptions for key product events, including document uploaded, analysis completed, summary generated, chat answer saved, report exported, and processing failed. Each subscription should support event selection, destination URL, signing secret, retry policy, delivery status, and a searchable delivery history.

Scope

• Backend API for creating, listing, testing, pausing, and deleting webhook subscriptions.
• Event publisher that emits normalized document and AI-analysis payloads without leaking private document content by default.
• Delivery worker with retries, exponential backoff, timeout handling, and idempotency keys.
• Frontend settings view for managing destinations, testing a delivery, and inspecting recent attempts.
• Documentation covering payload schema, signature verification, retry behavior, and security guidance.

Acceptance Criteria

• Users can create webhook subscriptions scoped to one or more supported event types.
• Delivered payloads include stable event ids, timestamps, event type, user id, document id, and safe analysis metadata.
• Webhook requests are signed with an HMAC secret and documented with verification examples.
• Failed deliveries are retried with bounded backoff and terminal failure states are visible in the UI.
• A delivery audit trail shows status code, attempt count, last error, next retry time, and sanitized response details.
• Tests cover subscription CRUD, signature generation, retry behavior, and event payload shape.

Non-Goals

• Building every third-party integration as a native app in this issue.
• Sending full document text or sensitive extracted content by default.
• Replacing infrastructure-level Slack/PagerDuty deployment alerts.

Dependencies / Risks

• Requires clear event naming and payload versioning so downstream integrations do not break.
• Needs careful treatment of secrets, retry storms, and sensitive payload fields.
• May depend on the existing async queue/RabbitMQ path for reliable delivery.

Open Questions

• Which events should be enabled in the first release?
• Should webhook subscriptions be per-user initially, or should this wait for organization/workspace ownership?
• Should Slack/Teams be implemented as separate convenience destinations after the generic webhook foundation lands?