AUTH-005: Organization-level leader-summary external Webhook

Status

Accepted

Date

2026-09-09

Context

AUTH-003 delivered privacy-bounded team-lead summaries through a leader-owned AgentBus channel and a learned WeChat route. The user later supplied a fixed external Webhook contract and clarified that only the organization-wide leader-summary transport should change; normal employee AgentBus task intake, replies, ownership, confirmation, ERP queues, and execution must remain unchanged.

The external API has no idempotency key, downstream delivery identifier, status query, or callback. A successful HTTP exchange can therefore prove only that the gateway accepted the request, while a timeout or lost response cannot distinguish “not received” from “accepted but response lost.”

Decision

Configure one organization-level leader-summary destination only through protected runtime values WEBHOOK_SEND_URL and WEBHOOK_EXTERNAL_TOKEN. Both must be present, the production URL must use HTTPS and end with /webhookInfo/sendMessageByOut, and the token must contain exactly 32 non-whitespace characters. The complete URL and token never enter the database, logs, audit, or administrator response.
Send exactly one POST JSON request with raw x-token and body {id:"9999", content:<summary>}. Only HTTP 200 with code === 0 and data === true is “accepted”; accepted does not mean delivered to WeChat.
Keep the projection organization-wide, future-only, and read-only. It covers stable manual and AgentBus outcomes for durably assigned non-administrator employees and retains the existing privacy allowlist, generic failure wording, and uncertain-write distinction. It never changes task ownership, employee replies, parser behavior, confirmation, queue state, browser claims, reconciliation, or ERP authority.
Store summary state and encrypted payloads only in the dedicated revisioned leader_task_summary_webhook_* tables. Each organization/revision/task/milestone is unique and may be attempted at most once.
Never automatically retry an explicit rejection, timeout, network failure, 5xx response, invalid or unknown response, oversized response, or expired sending lease. Mark ambiguous cases uncertain; configuration changes cancel unsent old-revision rows and make in-flight old-revision rows uncertain.
Isolate configuration, initialization, projection, database, and delivery failures inside the summary worker. They may disable or degrade summary delivery but cannot block the normal HTTP service or mutate ordinary tasks, employee agentbus_deliveries, AgentBus channels, parsing, or ERP execution.
Expose only a read-only administrator status with safe configuration state, bounded fingerprints, counts, and accepted/rejected/uncertain terminology. There is no administrator send-test or message-composer endpoint.

Rationale

A dedicated one-attempt Webhook outbox preserves the established privacy and task-authority boundaries while removing leader-summary dependence on a team-lead AgentBus account, channel, or learned conversation route. Treating ambiguous sends as terminal uncertainty is safer than automatic retry because the provider offers no deduplication or delivery evidence.

Consequences

Migrations must run in order through 022_shared_child_order_batch_create and 023_leader_summary_webhook_delivery before the integrated control plane starts.
Migration 023 disables legacy AgentBus summary subscriptions and cancels their unsent rows while preserving historical tables and already recorded outcomes. Normal employee agentbus_deliveries are untouched.
Production enablement requires the provider-confirmed complete gateway URL, the real 32-character token, database backup/migration, deployment/restart, and a separately authorized bounded external-send canary.
Repository tests and disposable PostgreSQL exercises prove isolation, encryption, one-attempt semantics, and accepted-versus-delivered wording; they do not prove live gateway or WeChat delivery.

Supersedes

AUTH-003 clauses that activate summaries from a team_lead identity plus owned AgentBus channel, learn or invalidate AgentBus/WeChat routes, prioritize summary frames inside AgentBus, or use at-least-once task.summary frames.

AUTH-003's organization-wide future-only projection, privacy allowlist, separate encrypted storage, and non-expansion of task/ERP authority remain active through this decision.

.project-docs/10-decisions/AUTH-003-leader-task-summary-notifications.md
.project-docs/10-decisions/AUTH-004-admin-management-plane-and-leader-oversight.md
.project-docs/30-worklog/tasks/20260908-leader-webhook-api-7c4e9a12.md
agent设计规范/leader-summary-webhook-contract.md
control-plane/migrations/023_leader_summary_webhook_delivery.sql
control-plane/src/external-webhook-client.ts
control-plane/src/leader-notification-service.ts

4.9 KiB Raw Blame History