# ISIS v2 Webhook Subscription APIs (WS10-004)

Date: 2026-02-24  
Owner: @oshun/isis-team  
Checklist: `WS10-004`  
Ticket: `ISIS2-00112`

## Objective

Add first-class webhook subscription management APIs for external orchestration
systems, with explicit RBAC, delivery policy controls, and SDK parity.

## Existing Implementations Reviewed

Before implementation, these in-repo references were analyzed:

- `docs/domains/lilith/extras/guides/webhooks.md` (`/v1/webhooks` CRUD + secret
  rotation)
- `docs/domains/veritas/extras/b2b-api/webhooks.md` (delivery retries, signature
  guidance, replay/idempotency expectations)
- `apps/isis/generation-api/src/routes/provider-callbacks.ts` (existing inbound
  provider webhook signature validation pattern)
- `apps/isis/generation-api/src/routes/workflows.ts` (RBAC helper pattern for
  mixed bearer/API-key auth)

Design decisions taken from this analysis:

- explicit subscription CRUD and lifecycle routes,
- one-time secret reveal on create/rotate, masked secret hints on reads,
- retry policy in contract (strategy + delay bounds + max attempts),
- event topic allowlist constrained to job/workflow/output lifecycle topics,
- route-level role/permission checks for both bearer and API keys.

## Delivered API Surface

Mounted under `generation-api`:

- `GET /api/v1/webhook-subscriptions/event-types`
- `POST /api/v1/webhook-subscriptions`
- `GET /api/v1/webhook-subscriptions`
- `GET /api/v1/webhook-subscriptions/:subscriptionId`
- `PATCH /api/v1/webhook-subscriptions/:subscriptionId`
- `DELETE /api/v1/webhook-subscriptions/:subscriptionId`
- `POST /api/v1/webhook-subscriptions/:subscriptionId/activate`
- `POST /api/v1/webhook-subscriptions/:subscriptionId/pause`
- `POST /api/v1/webhook-subscriptions/:subscriptionId/rotate-secret`

## RBAC Model

Read operations accept:

- roles: `admin`, `ops`, `sre`, `developer`, `viewer`
- permissions: `webhooks:read`, `integrations:webhooks:read`, `jobs:read`,
  `jobs:manage`, `workflows:read`, `*`

Write operations accept:

- roles: `admin`, `ops`, `sre`, `developer`
- permissions: `webhooks:manage`, `integrations:webhooks:manage`, `jobs:manage`,
  `workflows:write`, `*`

All routes require project scoping (`X-Isis-Project-Id` or scoped auth claim).

## Delivery Controls in Contract

Subscription payloads now support:

- endpoint URL policy (HTTPS required, localhost HTTP allowed for dev)
- event topic subscriptions
- custom headers (reserved header names blocked)
- retry policy (`strategy`, `initialDelayMs`, `maxDelayMs`, `maxAttempts`)
- status lifecycle (`active`, `paused`, `disabled`)
- signing secret management (create + rotate)

## Persistence and Runtime

A dedicated service/store was added:

- `WebhookSubscriptionService`
- `PostgresWebhookSubscriptionStore` with managed table/index creation
- soft-delete semantics and project-scoped uniqueness by subscription name

## SDK Parity

`@isis/client` `GenerationResource` now exposes typed methods for:

- event type discovery
- create/list/get/update/delete subscription
- activate/pause subscription
- rotate secret

A dedicated parity test verifies each SDK webhook-subscription operation maps to
an OpenAPI route.

## Verification Commands

```bash
pnpm --filter @isis/generation-api exec vitest run src/routes/webhook-subscriptions.spec.ts src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/client exec vitest run src/resources/generation.webhook-subscriptions.route-parity.spec.ts --reporter=dot
node scripts/isis/generate_generation_api_openapi.mjs --check
```
