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
EventSchemaRegistrypattern for contract-based event schema lookup.
- existing global
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-schemasGET /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.queuedjob.runningjob.completedjob.failedjob.cancelledworkflow.execution.queuedworkflow.execution.completedworkflow.execution.failedoutput.createdoutput.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#
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