Eve library

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

Guide

Revision 1

On this page

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