# ISIS v2 Webhook Event Payload Schema Registry (WS10-005)

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

## Objective

Add a canonical, machine-readable event payload schema registry for all webhook
job/workflow/output lifecycle topics exposed by Isis orchestration APIs.

## Existing Implementations Reviewed

Before implementation, these in-repo implementations were analyzed and reused:

- `libs/contracts/src/events/validation.ts`
  - existing global `EventSchemaRegistry` pattern for contract-based event
    schema lookup.
- `libs/contracts/src/events/isis.ts`
  - canonical Isis payload shape definitions for job and asset lifecycle events.
- `apps/isis/generation-api/src/routes/webhook-subscriptions.ts`
  - existing webhook discovery/auth/RBAC patterns and route mounting.

Design decisions from this analysis:

- keep schema registry canonical and typed in generation-api for external
  webhook topics,
- include both payload and delivery-envelope schemas for integration teams,
- publish versioned schema metadata and examples per event topic,
- expose list + single-schema lookup APIs with existing webhook read RBAC.

## Delivered API Surface

Added schema discovery routes under webhook subscriptions:

- `GET /api/v1/webhook-subscriptions/event-schemas`
- `GET /api/v1/webhook-subscriptions/event-schemas/:eventType`

Enhanced existing event-type discovery route with registry metadata:

- `GET /api/v1/webhook-subscriptions/event-types`

## Registry Coverage

The registry now defines versioned payload/envelope schemas for all webhook
lifecycle topics:

- `job.queued`
- `job.running`
- `job.completed`
- `job.failed`
- `job.cancelled`
- `workflow.execution.queued`
- `workflow.execution.completed`
- `workflow.execution.failed`
- `output.created`
- `output.archived`

Each entry includes:

- schema ID + version
- lifecycle topic metadata (`topic`, `lifecycleStage`)
- JSON Schema draft format
- payload schema
- delivery envelope schema
- example payload
- source internal event mapping metadata

## SDK Parity

`@isis/client` `GenerationResource` now supports typed schema-registry methods:

- `listWebhookEventSchemas(...)`
- `getWebhookEventSchema(eventType)`

Client types include registry metadata, payload schema contracts, and typed
response objects.

## Verification Commands

```bash
pnpm --filter @isis/generation-api exec vitest run src/routes/webhook-subscriptions.spec.ts src/app.auth.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
pnpm --filter @isis/generation-api run openapi:check
```
