PSA/docs/plans/2026-05-15-outbound-webhooks-for-projects/PRD.md

# PRD: Outbound Webhooks for Projects

- **Status:** Draft (loop-ready)
- **Owner:** Natallia Bukhtsik
- **Created:** 2026-05-15
- **Source draft:** `.ai/webhook-entity-metadata-registry-plan.md`
- **Branch:** `webhooks_expansion`

## 1. Problem statement & user value

Alga PSA delivers outbound webhooks for tickets but not for projects, even
though internal `PROJECT_*` / `PROJECT_TASK_*` events already fire on the event
bus. MSP integrators cannot react programmatically to project lifecycle changes
(creation, status, assignment, closure) or project-task changes. The outbound
webhook infrastructure (DB tables, vault-stored signing secrets, Redis-backed
`WebhookDeliveryQueue`, HMAC signing, retry, the `AdminWebhooksSetup` UI,
per-subscriber field allowlists) is **already entity-agnostic** — only the
ticket-specific glue is hardwired. This effort adds the project-specific glue so
subscribers can register project webhooks with the same field-allowlist control
they have for tickets.

## 2. Goals

- Deliver outbound webhooks for 5 project-level events and 5 project-task
  events through the existing queue/signing/retry pipeline.
- Per-subscriber field allowlist support for the new `project` entity, reusing
  the Phase 0 single-source `payloadFields.ts` registry and the existing
  projection helper.
- Opt-in sub-entity payload sections (`phases`, `task_counts`) mirroring the
  proven ticket `comments` batched-fetch pattern.
- Backward-compatible public webhook event enum (no breakage for existing
  `webhook_subscriptions` rows referencing `project.completed`).

## 3. Non-goals

- No webhook queue, schema, signing, or UI redesign (infra is reused as-is).
- No new operational tooling (monitoring/metrics/dashboards) — out of scope.
- No project-level tags in the payload (the tag system has no `project`
  tagged_type — see §7).
- `PROJECT_TASK_UPDATED` covers form-edit field changes and interactive tag
  changes only; status/phase-move/reorder/dependency mutations are explicitly
  out of scope (see §7).
- No generic `dispatchEntityWebhooks` abstraction yet (deferred follow-up).

## 4. Personas & primary flows

- **MSP integrator / admin:** In Settings → Security → Webhooks, registers a
  webhook for e.g. `project.created` + `project.status_changed`, selects a
  subset of payload fields (optionally `phases`), and receives signed HTTP
  deliveries when projects change.
- **External receiving system:** Gets the same envelope/signature contract as
  ticket webhooks; payload is projected to the subscriber's allowlist with
  `project_id` (and `task_id` for task events) always retained.

## 5. Scope: events

**Project-level** (entity `project`): `project.created`, `project.updated`,
`project.status_changed`, `project.assigned`, `project.closed`.

**Project-task** (entity `project`, routed via single-entity decision §6):
`project.task.created`, `project.task.updated`, `project.task.status_changed`,
`project.task.assigned`, `project.task.completed`.

Internal sources (verified present):
- `projectActions.ts` already emits `PROJECT_CREATED`, `PROJECT_UPDATED`,
  `PROJECT_STATUS_CHANGED`, `PROJECT_ASSIGNED`, `PROJECT_CLOSED`.
- `projectTaskActions.ts` already emits `PROJECT_TASK_CREATED`,
  `PROJECT_TASK_STATUS_CHANGED`, `PROJECT_TASK_ASSIGNED`,
  `PROJECT_TASK_COMPLETED`. `PROJECT_TASK_UPDATED` does **not** exist and is
  added by this work.

**Tag-driven updates (in scope — projects + tickets, parity).** Adding/removing
a tag on a project task or a ticket currently fires no per-entity event (tag
actions emit only `TAG_DEFINITION_UPDATED`), so it produces no webhook today.
This work adds emission of `PROJECT_TASK_UPDATED` / `TICKET_UPDATED` (with
`changes: { tags: {...} }`) from the interactive tag mutation path. These
surface as the existing `project.task.updated` / `ticket.updated` deliveries —
no new public event types. The ticket side is included for parity (same gap
exists for tickets today).

## 6. Resolved design decisions

1. **Single `project` allowlist entity** (user-confirmed 2026-05-15). Both
   project-level and task-level events route to entity `project`;
   `webhookEntityForEventType()` is unchanged (first-dot slice). Trade-off
   accepted: the field picker for a `project.created` webhook will list
   task-only fields (`task_name`, `phase_id`, …) the event never carries.
   Task events require `applyPayloadAllowlist('project', payload, allowlist,
   extraAlwaysIncluded:['task_id'])` so `task_id` survives projection.
2. **Helper rename:** `projectWebhookPayload` → `applyPayloadAllowlist` (verb
   collides with the new `project` noun domain). Done as an isolated mechanical
   refactor before project code is added.
3. **`project.completed` is a deprecated accepted alias** of `project.closed`
   (and `project.task.completed` retained likewise). The public enum keeps
   them; the event map resolves them to closed/completed semantics. Existing
   `webhook_subscriptions` rows are checked, not broken.
4. **Tag changes trigger webhooks for project tasks AND tickets**
   (user-confirmed 2026-05-15). Emit `PROJECT_TASK_UPDATED` / `TICKET_UPDATED`
   with `changes.tags` from the interactive tag path only. No new public event
   types — reuses `*.updated`. Ticket parity is explicitly in scope.

## 7. Constraints & corrected facts (must hold)

- **Phase 0 is already implemented** (single-source `payloadFields.ts`
  consolidation) and its tests pass. It is a *precondition*, verification-only,
  not buildable work. It should land as its own commit before Phase 1.
- **Tag system:** `shared/models/tagModel.ts` `tagged_type` enum is
  `['client','contact','project_task','document','knowledge_base_article']`.
  → `ProjectWebhookPayload` ships **without** `tags`.
  → `ProjectTaskWebhookPayload` uses `TagMapping.getByEntity(..., 'project_task')`.
- **`PROJECT_TASK_UPDATED` emit scope:** emitted from
  `updateTaskWithChecklist` (form field edits) **and** the interactive tag
  mutation path for `project_task` (F008, `changes.tags`). The other five
  task-mutation entry points (`updateTaskStatus`, `moveTaskToPhase`,
  `reorderTask`, `reorderTasksInStatus`, `updateTaskDependency`) intentionally
  do **not** emit it; they have dedicated events or no webhook-relevant delta.
- **Tag emission must not double-fire (F008).** `createTagsForEntity` runs at
  entity-creation time (`TaskForm.tsx:910`, immediately after
  `PROJECT_TASK_CREATED`). Tag-change emission is scoped to *interactive*
  single-entity mutations (`createTag` :101, `deleteTag` :335, `TagManager`
  onChange) only — never the bulk `createTagsForEntity` :534 /
  `createTagsForEntityWithTransaction` :571. No-op tag writes emit nothing.
- **Ticket parity (F008):** the ticket webhook builder already attaches
  `changes` on `TICKET_UPDATED` (`webhookTicketPayload.ts:143`), so the ticket
  side needs no builder change — only the event emission from `tagActions.ts`.
- **Strict type:** keep `ALWAYS_INCLUDED_KEYS_BY_ENTITY` typed
  `as const satisfies Record<WebhookPayloadEntity, readonly string[]>` — do not
  loosen to `Record<string, …>`.
- The projection helper now lives in `server/src/lib/webhooks/payloadFields.ts`
  (Phase 0 moved it out of `webhookTicketPayload.ts`).

## 8. Data / API integration notes

- New internal event `PROJECT_TASK_UPDATED` in
  `packages/event-schemas/src/schemas/eventBusSchema.ts`: payload
  `{ tenantId, projectId, projectTaskId, phaseId, userId?, occurredAt?,
  changes?: Record<string,{previous,new}> }`; add to event-type enum,
  `EventSchemas` map, inferred type export.
- `ProjectWebhookPayload` (no `tags`): `project_id` (always), `project_name`,
  `wbs_code`, `description`, `status_id`, `status_name`, `is_closed`,
  `previous_status_id?`, `previous_status_name?`, `client_id`, `client_name`,
  `contact_name_id`, `contact_name`, `contact_email`, `assigned_to`,
  `assigned_to_name`, `start_date`, `end_date`, `budgeted_hours`,
  `url=${NEXTAUTH_URL}/msp/projects/${project_id}`, `changes?`, `phases?`,
  `task_counts?`.
- `ProjectTaskWebhookPayload`: project context (`project_id`, `project_name`,
  `client_id`, `client_name`) + `task_id`, `phase_id`, `phase_name`,
  `task_name`, `description`, `status_id`, `status_name`, `is_closed`,
  `previous_status_id?`, `previous_status_name?`, `assigned_to`,
  `assigned_to_name`, `estimated_hours`, `actual_hours`, `due_date`,
  `priority_id`, `priority_name`, `wbs_code`,
  `url=${NEXTAUTH_URL}/msp/projects/${project_id}?taskId=${task_id}` (verify
  route), `tags` (via `project_task`), `changes?`.
- Public OpenAPI schema auto-extends from `WEBHOOK_PAYLOAD_FIELDS_BY_ENTITY`
  (Phase 0 generates the per-entity enum from this map — no manual doc edits).

## 9. Risks, rollout, open questions

- **Rollout:** additive; project webhooks go live only when
  `projectWebhookSubscriber` is registered in `subscribers/index.ts`
  (last feature). Public enum aliasing prevents subscription-row breakage.
- **Risk:** task-payload `url` route shape unverified — confirm
  `/msp/projects/:id?taskId=:taskId` against the app router before shipping.
- **Open question (non-blocking):** product may later want project-level tags;
  requires a tag-system change, tracked as a follow-up, not this plan.
- **Follow-up (deferred):** extract `dispatchEntityWebhooks(entity, event,
  builder)` once ticket + project subscribers both exist (~80% shared body).

## 10. Acceptance criteria / definition of done

- All 10 project/task public events are registrable in the Webhooks UI and the
  public API enum, with `project.completed` / `project.task.completed`
  accepted as deprecated aliases (no existing-subscription breakage).
- Creating/updating/closing a project and creating/updating/completing a task
  produces a signed HTTP delivery and a `webhook_deliveries` row, payload
  correctly projected to the subscriber allowlist with `project_id`
  (and `task_id` for task events) always present.
- `phases` / `task_counts` populate only when in the allowlist or full payload,
  fetched once per event regardless of subscriber count.
- No project-level `tags`; task `tags` resolve via `project_task`.
- `applyPayloadAllowlist` rename complete, all callers/tests green.
- Adding/removing a tag on a project task delivers `project.task.updated`
  with a `changes.tags` diff; on a ticket delivers `ticket.updated` likewise;
  creating an entity with initial tags does not double-fire; no-op tag writes
  emit nothing.
- Full webhook unit + integration suite green; workspace type-check clean.

## 11. Loop execution notes

- 8 coarse features; each is one self-contained commit. Execution order is
  array order in `features.json`:
  `F001 → F002 → F003 → F008 → F004 → F005 → F006 → F007`
  (IDs are stable, not sequential — `F008` runs 4th, right after the
  `PROJECT_TASK_UPDATED` event it depends on exists).
- `F001` is the already-done Phase 0 precondition (`implemented: true`,
  verification + standalone commit only — the loop must not rebuild it).
- Ordering is dependency-safe: rename → event → tag-emission → registration →
  builders → subscriber → tests. Pure-new-code features (`F005`) have no
  callers until `F006` registers the subscriber.
- Per-repo policy, commits/pushes happen only on explicit user request even
  inside the loop.