PSA/ee/docs/plans/2026-05-11-inbound-webhooks/PRD.md

PRD — Inbound Webhooks

• Slug: 2026-05-11-inbound-webhooks
• Date: 2026-05-11
• Status: Draft

Summary

Add user-configurable inbound webhook endpoints to Alga PSA so MSPs can wire external systems (RMM alerts, accounting platforms, Zapier/n8n, custom integrations) into Alga without writing code. Each inbound webhook accepts authenticated HTTP requests, verifies them, dedupes replays, logs the delivery, and dispatches the payload to one of two handlers:

1. Direct action — invoke a canned operation (create ticket, update ticket by external ref, upsert asset, mark invoice paid) with field-level mapping from the payload.
2. Workflow trigger — start an Alga workflow with a normalized envelope containing the body, headers, and verification metadata.

Outbound webhooks already exist; this work surfaces both inbound and outbound under a unified Settings → Webhooks page.

Problem

Today, the only way to move data into Alga from external systems is the public REST API or one of the purpose-built integrations (NinjaOne RMM, Tactical RMM, Tanium, Xero, QBO, Entra, Microsoft Graph, Google). Those bundled integrations work well for the systems they cover but don't help MSPs who:

• Use an RMM Alga doesn't have a bundled integration for (e.g. N-able, Auvik, Liongard, Kaseya, Pulseway, or in-house monitoring).
• Run custom internal tooling (scripts, dashboards, alerting glue) that emits JSON over HTTP.
• Use automation platforms (Zapier, n8n, Make) where the only thing required is a URL that accepts a webhook.
• Want a non-RMM signal to drive an Alga action (e.g. SIEM alert → ticket, build failure → ticket, payment gateway event → invoice paid for a payment processor we don't bundle).

The existing bundled integrations already use inbound webhook patterns internally (NinjaOne has webhookHandler.ts + alertProcessor.ts + ticketCreator.ts; Tactical RMM stores a webhook secret). This work generalizes the pattern: any MSP admin can wire any HTTP source to any Alga entity action or workflow without code.

Result: integration friction is the #1 reason MSPs report Alga "doesn't fit our stack."

Goals

• MSP admins can create, edit, and delete inbound webhook configurations from Settings → Webhooks.
• Each inbound webhook has a unique URL, a configurable authentication scheme, and a handler (direct action OR workflow).
• Verified payloads are persisted, deduped, and visible in a delivery log with replay capability.
• Direct-action coverage spans the major mutable entities — tickets, clients, contacts, assets, invoices, time entries, project tasks, plus a cross-cutting tag action. An action registry pattern lets any @alga-psa/* package contribute additional actions without touching the inbound webhook core.
• External-ID lookup for "update by external reference" operations uses the existing tenant_external_entity_mappings table — no new per-entity external_ref columns.
• Workflow handlers receive a parsed, normalized envelope that includes raw body and headers, so workflow authors don't reimplement parsing.
• Field mapping reuses the existing workflow expression editor (JSONata + Monaco) — no new mapping UI is built from scratch.
• Asset upsert via inbound webhook reuses the existing ingestNormalizedRmmDeviceSnapshot pipeline (used by Tanium, NinjaOne, Tactical RMM) so device data flows through the same normalization path as bundled RMM integrations.

Non-goals

• Per-source presets (preconfigured templates for specific RMM/accounting vendors). v1 ships generic config only; presets land in v2 once we see real-world payload shapes from custom configurations.
• Refactoring existing bundled integrations (NinjaOne, Tactical RMM, Tanium, Xero, QBO, Entra) to ride on the user-configurable system. They continue working as today. Consolidation is a separate v2+ effort.
• Visual drag-drop field mapper. JSONata text editor (already used in workflow editor) is the only mapping UX.
• Per-source normalizer shims. The "normalized envelope" is identity in v1: {source: slug, body, headers, verified, delivery_id}.
• Public Zapier/n8n/Make app listings in their directories. The inbound endpoint enables those integrations; building distributable apps is separate work.
• Outbound webhook feature changes beyond UI re-layout (tabbed under Settings → Webhooks).
• Multi-handler chains per webhook (run action AND workflow). One handler per webhook in v1.
• Client Portal webhook configuration. MSP portal only.
• Bidirectional sync semantics — inbound webhooks are one-way (external → Alga). Writing back to external systems is a separate outbound-webhook concern.

Users and Primary Flows

Primary persona: MSP Admin (technical, comfortable with HTTP/JSON, may not be a developer).

Flow A — Wire RMM alert to create a ticket (direct action):

1. Admin navigates to Settings → Webhooks → Inbound tab → "New Webhook."
2. Names it ("ConnectWise Alerts"), picks auth method (HMAC-SHA256), generates a secret.
3. Picks handler type "Direct Action," selects "Create Ticket" from action dropdown.
4. UI renders the target field list for createTicket (title, description, priority, asset_id, external_ref, etc.). Each target field has an ExpressionTextArea for JSONata mapping.
5. Admin captures a sample payload by sending one test request to the URL (capture mode). The expression editor's autocomplete now suggests paths from the captured sample.
6. Admin maps title ← alert.message, priority ← alert.severity, external_ref ← alert.id, etc.
7. Saves. Copies URL + secret into ConnectWise.
8. Real alert arrives → verified → mapped → ticket created. Delivery shows in the log.

Flow B — Wire alert to a workflow (workflow handler):

1. Same setup as A, but handler type "Workflow."
2. Admin picks an existing workflow from a dropdown (e.g. "Triage Critical Alert").
3. Payload arrives → workflow starts with context.input = { source: "connectwise-alerts", body: {...}, headers: {...}, verified: true, delivery_id, idempotency_key }.
4. Workflow branches, calls actions, creates tickets, pages on-call.

Flow C — Debug a failed delivery:

1. Admin opens delivery log row → sees full request body, headers, response, latency, error.
2. Clicks "Replay" → request is re-dispatched against current config (with current mapping/handler).
3. Replay shows as a new delivery row marked as a replay.

UX / UI Notes

• Existing AdminWebhooksSetup.tsx (Settings → Security) becomes the Outbound tab in a new AdminWebhooksSetup containing two tabs (Inbound | Outbound). No regressions to outbound feature set.
• Inbound list view mirrors outbound: table with name, URL, handler type, last delivery, active state, kebab menu.
• Inbound create/edit dialog has sections: Identity (name, slug), Auth (method + config), Idempotency (key source), Handler (type + action/workflow + mapping), Active.
• Handler section is conditional:
  • Direct Action: dropdown of supported actions; below that, the action's target fields rendered as labeled ExpressionTextArea rows. A side panel shows the captured sample payload tree for click-to-insert path.
  • Workflow: dropdown of tenant's workflows; an info card explains the envelope shape the workflow receives.
• Sample payload capture: button "Capture sample request" toggles a 5-minute capture window. The first verified request lands in the editor as the schema source. Re-capture overwrites.
• Delivery log: identical shape to outbound delivery log (drawer with request/response, replay button).
• All strings via t('translation.key') (i18n requirement per CLAUDE.md).
• All interactive elements need id attributes (UI reflection requirement per CLAUDE.md).

Requirements

Functional Requirements

Configuration:

• F-CRUD inbound webhook configs: name, slug (URL-safe, unique per tenant), is_active, description.
• F-Auth schemes: HMAC-SHA256 (configurable signature header name + secret), Bearer token, IP allowlist (CIDR list), Shared-secret-in-path (?token=).
• F-Auth secrets stored in the secrets vault; never returned in API responses after creation.
• F-Idempotency key source: HTTP header name (e.g. X-Idempotency-Key) OR JSONata expression evaluated on the body (e.g. alert.id). Configurable per webhook.
• F-Duplicate detection: within a configurable window (default 24h), same idempotency key returns 200 OK no-op without re-dispatching.

Endpoint:

• F-Catch-all route: POST /api/inbound/[tenant_slug]/[webhook_slug] (also accepts PUT, PATCH if the source needs it).
• F-Tenant slug resolution from URL → tenant context bootstrapped before further processing.
• F-Auth verification per config; rejected requests get 401 with no body details (avoid leaking config).
• F-Successful verification stores a delivery row before dispatch (so failed dispatches are still visible).
• F-Response: 200 OK with {delivery_id} on accepted; 4xx for auth/validation; 5xx for internal dispatch failure.

Direct Action Handler:

• F-Action registry pattern: each @alga-psa/* package contributes inbound-callable actions via a typed registration (name, entityType, targetFields[], handle()). Core lives in server/src/lib/inboundWebhooks/actions/registry.ts.
• F-V1 ships the following actions:
  • Tickets: createTicket, updateTicketByExternalId, addTicketCommentByExternalId, changeTicketStatusByExternalId
  • Clients: upsertClientByExternalId, setClientActiveByExternalId
  • Contacts (client_users): upsertContactByExternalId
  • Assets: upsertAssetByExternalId — routes through existing ingestNormalizedRmmDeviceSnapshot from @alga-psa/integrations/lib/rmm/sharedAssetIngestionService when payload is flagged as an RMM device snapshot; otherwise plain asset upsert
  • Invoices: markInvoicePaidByExternalId, updateInvoiceStatusByExternalId
  • Time Entries: createTimeEntry
  • Project Tasks: createProjectTask, updateProjectTaskStatusByExternalId
  • Cross-cutting: addTagToEntityByExternalId (accepts target entity_type)
• F-Action selector dropdown in UI, grouped by entity type.
• F-Each action declares its target field list (typed: string, int, enum, ref-to-entity), with required/optional flags.
• F-Field mapping: each target field is a JSONata expression evaluated against the request body.
• F-*ByExternalId actions look up the target entity via tenant_external_entity_mappings using integration_type = webhook_slug, alga_entity_type = <ticket|client|asset|...>, external_entity_id = <mapped value>. No new external_ref columns are added to entity tables.
• F-Create actions (createTicket, upsertClient*, upsertContact*, upsertAsset*) MAY optionally write a mapping row when an external_id field is mapped — so subsequent webhooks can resolve back to the created entity.
• F-Lookup miss on update* / addComment* / markPaid* actions returns a failed delivery (not silent no-op).
• F-Validation errors (missing required mapped field, type mismatch) record a failed delivery with a clear error message.

Workflow Handler:

• F-Workflow selector dropdown (lists tenant's workflows).
• F-Payload envelope: { source: webhook_slug, body: parsed_json, headers: filtered_safe_headers, verified: true, delivery_id, idempotency_key, received_at }.
• F-Workflow run is triggered with the envelope as context.input.
• F-Workflow failure does NOT mark inbound delivery failed; the delivery's job was to start the workflow, not complete it. Delivery log links to the workflow run for debugging.

Field Mapping UX (reuse workflow expression editor):

• F-Reuse ExpressionTextArea and ExpressionEditor from ee/server/src/components/workflow-designer/.
• F-New webhook payload context adapter (webhookPayloadContextAdapter.ts) that introspects a captured sample payload to feed autocomplete.
• F-Sample payload capture: a "capture next request" mode that stores the first verified body to the webhook config; the editor reads from this for autocomplete.
• F-Editor diagnostics: invalid JSONata path → inline warning. Type mismatch (e.g. mapping string to int field) → inline warning.

Delivery Log:

• F-Persist every verified request: request body, headers (filtered), response status, response body, latency, handler outcome, error message, retry count.
• F-Auth-rejected requests logged separately with limited detail (no body) to support abuse triage.
• F-List view filtered by webhook, date range, status.
• F-Detail drawer mirrors outbound's.
• F-Replay button re-dispatches against current config; result is a new delivery row tagged is_replay=true, replayed_from=<original_id>.

Permissions:

• F-New permission resource inbound_webhook with create, read, update, delete, replay actions.
• F-Outbound webhook permissions unchanged.
• F-admin role gets full inbound_webhook permissions by default.

Non-functional Requirements

• N-Multi-tenant isolation: all queries scoped by tenant; slug uniqueness enforced per-tenant.
• N-Auth failures are constant-time where possible (HMAC compare via crypto.timingSafeEqual).
• N-Rate limit: per-webhook configurable limit (default 600/min), Redis-backed token bucket. Distinct from outbound rate limiter — share the bucket implementation, not the instance.
• N-Storage: raw delivery body retained 30 days, then truncated to a fixed-size head + metadata; status/idempotency keys retained longer for dedup integrity.
• N-Webhook URL slugs are URL-safe ASCII; tenant slug derives from existing tenant identifier (must already exist or we add one).

Data / API / Integrations

New tables

• inbound_webhooks

  • inbound_webhook_id (pk, uuid), tenant (fk, always in pk per CitusDB rule), name, slug, description
  • auth_type (enum: hmac_sha256, bearer, ip_allowlist, path_token)
  • auth_config (jsonb: per-type — signature header, secret_vault_path, ip_cidrs, etc.)
  • idempotency_source (jsonb: {type: 'header'|'jsonata', value: string})
  • idempotency_window_seconds (default 86400)
  • handler_type (enum: direct_action, workflow)
  • handler_config (jsonb: for direct_action {action: string, field_mapping: {field: jsonata_expression}}; for workflow {workflow_id})
  • sample_payload (jsonb, nullable — captured sample for autocomplete)
  • is_active, auto_disabled_at, created_at, updated_at, created_by

• inbound_webhook_deliveries

  • delivery_id (pk), tenant (in pk), inbound_webhook_id (fk)
  • idempotency_key (nullable), received_at
  • request_method, request_path, request_headers (jsonb, filtered), request_body (jsonb or text)
  • source_ip, user_agent
  • auth_status (verified | rejected_signature | rejected_bearer | rejected_ip | rejected_no_auth)
  • dispatch_status (pending | dispatched | duplicate | failed)
  • handler_outcome (jsonb: action result or workflow_run_id, error message)
  • response_status, response_body, duration_ms
  • is_replay, replayed_from (nullable fk)

Reused existing tables

• tenant_external_entity_mappings (already exists; migration 20250502173321_create_tenant_external_entity_mappings.cjs) is the canonical external-ID-to-Alga-entity lookup. The inbound webhook system uses integration_type = <webhook_slug> to namespace mappings per webhook config.
• Schema: (tenant_id, integration_type, alga_entity_type, alga_entity_id, external_entity_id, external_realm_id, sync_status, last_synced_at, metadata).
• Unique indexes guarantee (tenant_id, integration_type, alga_entity_type, alga_entity_id) is one-to-one with the external side.
• No new external_ref columns are added to tickets, assets, invoices, etc. Lookups go through this table.

Asset ingestion reuse

• upsertAssetByExternalId delegates to ingestNormalizedRmmDeviceSnapshot from @alga-psa/integrations/lib/rmm/sharedAssetIngestionService when the mapped payload conforms to the device-snapshot shape — same path used by Tanium, NinjaOne, and Tactical RMM. For non-device assets, a simpler assets upsert is used.

Server actions (in server/src/lib/actions/inboundWebhookActions.ts)

• listInboundWebhooks(), getInboundWebhook(id), upsertInboundWebhook(input), deleteInboundWebhook(id)
• rotateInboundWebhookSecret(id), setInboundWebhookActiveState(id, active)
• listInboundDeliveries(filter, page), getInboundDelivery(id), replayInboundDelivery(id)
• captureSamplePayload(id) (toggles capture mode), clearSamplePayload(id)
• sendInboundWebhookTest(id, body, headers) (synthetic request for UI testing)
• All wrapped in withAuth per CLAUDE.md pattern.

Inbound HTTP route

• server/src/app/api/inbound/[tenantSlug]/[webhookSlug]/route.ts
• Handlers for POST, PUT, PATCH.
• Tenant resolution → config lookup → auth → idempotency → persist delivery → dispatch → respond.

Public REST API and OpenAPI registration

The inbound webhook system has two API surfaces that must be registered in the OpenAPI spec at server/src/lib/api/openapi/registry.ts and a new file server/src/lib/api/openapi/routes/inboundWebhooks.ts:

Management API (mirrors outbound webhook API at /api/v1/webhooks/*):

• GET /api/v1/inbound-webhooks — list
• POST /api/v1/inbound-webhooks — create
• GET /api/v1/inbound-webhooks/{id} — read
• PUT /api/v1/inbound-webhooks/{id} — update
• DELETE /api/v1/inbound-webhooks/{id} — delete
• POST /api/v1/inbound-webhooks/{id}/rotate-secret
• POST /api/v1/inbound-webhooks/{id}/test — synthetic dispatch
• POST /api/v1/inbound-webhooks/{id}/capture-sample / DELETE — sample capture toggle
• GET /api/v1/inbound-webhooks/{id}/deliveries — delivery log list
• GET /api/v1/inbound-webhooks/{id}/deliveries/{deliveryId}
• POST /api/v1/inbound-webhooks/{id}/deliveries/{deliveryId}/replay

Action discovery API:

• GET /api/v1/inbound-webhooks/actions — returns the registered action set: [{ name, entityType, displayName, description, targetFields: [{name, type, required, description, enumValues?}] }]. Lets SDK clients and external tooling build mapping UIs without hardcoding the action list.

Receiver endpoint:

• POST /api/inbound/{tenantSlug}/{webhookSlug} — registered as a single templated entry. Body is application/json (per-webhook shape varies). Documented headers: signature header (configurable name), idempotency key header, content-type. Response codes: 200, 401, 409 (duplicate idempotency), 429, 4xx, 5xx. Response body: {delivery_id} on success.

Schemas registered in OpenAPI components:

• InboundWebhookConfig, InboundWebhookCreateInput, InboundWebhookUpdateInput
• InboundWebhookAuthConfig (discriminated union by auth_type)
• InboundWebhookHandlerConfig (discriminated union by handler_type)
• InboundWebhookDelivery
• InboundActionDefinition, InboundActionTargetField
• WorkflowWebhookEnvelope — the envelope shape workflow handlers receive ({source, body, headers, verified, delivery_id, idempotency_key, received_at})

Generation and validation:

• After registration, sdk/scripts/generate-openapi.ts regenerates alga-openapi.{ce,ee}.{yaml,json}.
• New contract tests under server/src/test/unit/api/ follow the projectTasksOpenApi.contract.test.ts pattern: assert handler types match the registered schema.
• Generated SDK clients (in sdk/) pick up the new endpoints on next generation.

Action handler registry

• server/src/lib/inboundWebhooks/actions/registry.ts — central registry with registerAction(def) and listActions().
• Each action exports { name, entityType, displayName, description, targetFields[], handle(ctx, mapped_values) }.
• Actions live alongside the entity they target (e.g. packages/tickets/src/actions/inboundActions.ts, packages/clients/src/actions/inboundActions.ts) and call into the same internal handlers used by existing server actions. The registry imports each package's contributions at startup.
• UI dropdown is grouped by entityType and populated dynamically from the registry.
• Adding a new action in v2+ is a single file in the relevant package + a registerAction() call — no inbound webhook core changes needed.

Workflow trigger integration

• Identify the workflow engine's external-trigger entrypoint (likely an event bus publish or direct startWorkflow).
• Implementation note: webhookSubscriber.ts pattern is for outbound only; inbound needs the reverse direction. Spike during implementation.

Expression editor reuse

• Import ExpressionTextArea from ee/server/src/components/workflow-designer/mapping/.
• New context adapter at shared/workflow/expression-authoring/adapters/webhookPayloadContextAdapter.ts that returns the captured sample's path tree.

Security / Permissions

• New permission inbound_webhook with create | read | update | delete | replay.
• HMAC verification uses crypto.timingSafeEqual.
• Bearer comparison also timing-safe.
• Auth secrets in vault, never returned in API responses (only at creation, one-time display).
• Auth-rejected requests log limited detail (no body) — separate retention so they can be purged faster.
• Sample payloads may contain PII (device names, financial data) — mark as sensitive; only retrievable by webhook owner; redact obvious patterns (credit card-like, email-like) on display? Open question.
• Slug enumeration: 401 responses identical for "unknown slug" vs "bad auth" to avoid leaking which webhooks exist.

Rollout / Migration

• One migration creates inbound_webhooks and inbound_webhook_deliveries (Citus-distributed by tenant).
• Migrations to add external_ref/external_id columns are additive, nullable, indexed.
• New inbound_webhook permission seeded into the existing role-permission seed for admin role.
• Settings page UI changes are tabbed; existing outbound users see no behavior change, just a new tab.
• Feature flag inbound_webhooks_enabled (PostHog) to gate the Settings UI tab and the /api/inbound/* route. Default off for first release; enable per-tenant for early MSPs.

Open Questions

1. Workflow trigger entrypoint — does the engine accept synchronous startWorkflow(workflowId, input) calls, or must inbound dispatch via an event bus publish? Reference existing inbound trigger paths in NinjaOne (alertProcessor.ts) which may already invoke workflows. Spike before sprint start.
2. Tenant slug source — do tenants already have a URL-safe slug, or do we need to add one? Affects URL stability.
3. Sample payload PII redaction — do we redact on display, on capture, or trust the admin? Lean toward "no redaction, mark sensitive, admin-only access."
4. Mapping table integration_type namespace collisions — bundled integrations write to tenant_external_entity_mappings with integration_type values like 'ninjaone', 'tactical_rmm'. User-defined webhook slugs must not collide with these reserved values. Solution: prefix user slugs with user: (e.g. user:my-monitor) or maintain a reserved-name list. Decide before F032.
5. Replay against current config vs original config — replaying after the mapping has changed: re-evaluate with current mapping (current plan) or store the original mapping snapshot with the delivery? Current plan = simpler, may surprise users.
6. Action registration order / discovery — registry needs all package contributions loaded before the dropdown renders. Static imports vs dynamic discovery? Static is simpler; dynamic supports plugins later.
7. Optional v1 action: attachDocumentByExternalId — adding a note/document to an entity is common for "this alert details" use cases. Defer to v1.1 unless user requests.
8. Consolidation with bundled integrations — should NinjaOne / Tactical RMM eventually consume the same user-configurable webhook plumbing (with their secrets preset)? Out of scope for v1; flag as v2 candidate.

Acceptance Criteria (Definition of Done)

1. MSP admin can create an inbound webhook via Settings → Webhooks → Inbound, receive a URL + secret, and POST an HMAC-signed JSON request → response 200 OK with delivery_id.
2. Direct action createTicket with a JSONata field mapping creates a ticket whose fields match the mapped payload values; if an external_id is mapped, a row is written to tenant_external_entity_mappings.
3. updateTicketByExternalId resolves the ticket via tenant_external_entity_mappings (using integration_type = webhook_slug) and applies status / priority / assignment / board updates per mapping.
4. Workflow handler triggers a workflow run; workflow's context.input matches the documented envelope shape.
5. Duplicate idempotency keys within the window return 200 OK without re-dispatching.
6. Delivery log shows request, response, status, latency; failed deliveries show error messages.
7. Replay button creates a new delivery linked to the original.
8. JSONata expression editor (reused from workflow designer) provides autocomplete against the captured sample payload.
9. Outbound webhook feature regression: all existing outbound tests pass; UI is now tabbed but functionality unchanged.
10. Auth: HMAC, Bearer, IP-allowlist, and path-token schemes each reject mismatched requests with 401 and accept matching ones.
11. Permissions: a user without inbound_webhook:create cannot create inbound webhooks via the UI or server action.
12. Citus rule compliance: every query includes tenant; new tables use composite PKs including tenant.
13. i18n: no hardcoded English strings in new UI components.
14. Feature flag inbound_webhooks_enabled correctly gates UI and route.
15. Action registry includes all v1 actions (13 actions across 8 entity types: ticket×4, client×2, contact×1, asset×1, invoice×2, time_entry×1, project_task×2, cross-cutting tag×1) and dropdown groups them by entity type.
16. upsertAssetByExternalId for RMM-shaped payloads delegates to ingestNormalizedRmmDeviceSnapshot and produces the same asset record shape as Tanium / NinjaOne / Tactical RMM ingestion.
17. Bundled integrations (NinjaOne, Tactical RMM, Tanium, Xero, QBO, Entra) continue to function unchanged — no regressions in their existing inbound webhook paths.
18. Reserved integration_type values from bundled integrations cannot be used as user webhook slugs (or user slugs are namespaced to avoid collision).
19. All /api/v1/inbound-webhooks/* management endpoints + the templated /api/inbound/{tenantSlug}/{webhookSlug} receiver endpoint are registered in the OpenAPI spec; generated alga-openapi.{ce,ee}.{yaml,json} files include them.
20. GET /api/v1/inbound-webhooks/actions returns the registered action set with target field schemas; SDK consumers can build mapping UIs from this response without hardcoding actions.
21. OpenAPI contract tests pass for every new management endpoint, asserting handler types match registered schemas.