Eve library

ISIS v2 Webhook Subscription APIs (WS10-004)

Guide

Revision 1

On this page

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