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/webhooksCRUD + 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-typesPOST /api/v1/webhook-subscriptionsGET /api/v1/webhook-subscriptionsGET /api/v1/webhook-subscriptions/:subscriptionIdPATCH /api/v1/webhook-subscriptions/:subscriptionIdDELETE /api/v1/webhook-subscriptions/:subscriptionIdPOST /api/v1/webhook-subscriptions/:subscriptionId/activatePOST /api/v1/webhook-subscriptions/:subscriptionId/pausePOST /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:
WebhookSubscriptionServicePostgresWebhookSubscriptionStorewith 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