Eve library

OSHUN Studio Webhooks and External Automation Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security + Platform SRE + OSHUN Data/Analytics Engineering
Last Updated: 2026-02-23
Related: docs/adr/ADR-0047-oshun-studio-webhooks-and-external-automation.md

Purpose#

Define dependencies and canonical contracts for Studio webhooks and external automation across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00274.

Sources Used#

  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md
  • docs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.md
  • docs/adr/ADR-0047-oshun-studio-webhooks-and-external-automation.md
  • apps/iris/developer-portal/src/services/webhook-management-service.ts
  • apps/iris/api/src/docs/index.ts
  • apps/psyche/admin/src/api/client.ts
  • apps/isis/cli/src/commands/generate.ts
  • apps/bellona/build-api/src/main.ts
  • docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md
  • docs/releases/v1/runbooks/on-call-runbook.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md

1. Dependency Overview#

1.1 Control Surfaces#

  • Webhook governance UI surfaces: Studio webhook and automation modules in apps/oshun/web/src/components/studio.
  • Subscription lifecycle services: create/update/pause/activate/delete and secret rotation paths.
  • Delivery services: signed payload dispatch, retry/backoff, and terminal failure handling.
  • Automation execution services: external callback-triggered workflow orchestration.
  • Policy and approval services: role/tier/approval governance for sensitive automation actions.
  • Telemetry and audit services: delivery metrics, traceability, and evidence retention.

1.2 Domain Dependency Graph#

  • Webhooks/Automation -> Yemaya: release and workflow automation callbacks.
  • Webhooks/Automation -> Isis: model pipeline completion and orchestration callbacks.
  • Webhooks/Automation -> Hathor: narrative pipeline and editorial automation callbacks.
  • Webhooks/Automation -> Aja: rendering/timeline automation and completion callbacks.
  • Webhooks/Automation -> Bellona: runtime safety and build/release automation callbacks.
  • Project Obsidian -> all: cross-domain external automation governance and orchestration.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Subscription registry and lifecycle OSHUN BFF + Security Web operators + integration teams Subscription records StudioWebhookSubscriptionDefinition
Delivery execution and retry tracking Platform SRE + BFF Integration operators + on-call Delivery attempt stream StudioWebhookDeliveryAttempt
Signature and verification context Security Receivers + compliance operations Verification envelope StudioWebhookVerificationContext
Automation action request governance Program Ops + Security Studio automation operators Automation request envelope StudioAutomationActionRequest
Automation execution and callback state Platform SRE + domain ops Incident responders + release ops Execution lifecycle stream StudioAutomationExecutionEvent
Governance audit evidence Security + Data Platform Compliance + audit operations Audit event stream StudioWebhookGovernanceAuditEvent

3. Canonical Contracts#

3.1 StudioWebhookSubscriptionDefinition#

ts
export interface StudioWebhookSubscriptionDefinition {
  subscriptionId: string;
  owner: string;
  destinationUrl: string;
  eventTypes: string[];
  sourceDomains: Array<
    'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun'
  >;
  signingAlgorithm: 'hmac_sha256';
  status: 'active' | 'paused' | 'disabled';
  version: string;
  createdAt: string;
  updatedAt: string;
}

3.2 StudioWebhookDeliveryAttempt#

ts
export interface StudioWebhookDeliveryAttempt {
  attemptId: string;
  subscriptionId: string;
  eventId: string;
  deliveryStatus: 'queued' | 'delivered' | 'retrying' | 'failed_terminal';
  retryCount: number;
  maxRetries: number;
  responseCode?: number;
  latencyMs: number;
  nextRetryAt?: string;
  occurredAt: string;
}

3.3 StudioWebhookVerificationContext#

ts
export interface StudioWebhookVerificationContext {
  contextId: string;
  subscriptionId: string;
  signatureHeader: string;
  signatureVersion: string;
  timestampHeader: string;
  idempotencyKey: string;
  verified: boolean;
  reasonCode?: string;
  verifiedAt: string;
}

3.4 StudioAutomationActionRequest#

ts
export interface StudioAutomationActionRequest {
  requestId: string;
  action:
    | 'trigger_release_pipeline'
    | 'trigger_remediation_pipeline'
    | 'trigger_incident_callback'
    | 'pause_subscription'
    | 'resume_subscription';
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  targetSubscriptionId?: string;
  requestedAt: string;
}

3.5 StudioAutomationExecutionEvent#

ts
export interface StudioAutomationExecutionEvent {
  executionId: string;
  requestId: string;
  action: string;
  targetSystem: string;
  success: boolean;
  latencyMs: number;
  callbackReceived: boolean;
  errorCode?: string;
  executedAt: string;
}

3.6 StudioWebhookGovernanceAuditEvent#

ts
export interface StudioWebhookGovernanceAuditEvent {
  eventId: string;
  action:
    | 'webhook.subscription.created'
    | 'webhook.delivery.retried'
    | 'webhook.delivery.failed_terminal'
    | 'webhook.signature.verification_failed'
    | 'automation.request.denied'
    | 'automation.execution.completed';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  subscriptionId?: string;
  requestId?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Subscriptions must include destination URL, event types, owner, and signing metadata.
  • Delivery attempts must record retries, response status, and terminal outcomes.
  • Verification context must include signature/timestamp/idempotency identity.
  • Automation requests must enforce role/tier/approval controls by action and channel.
  • Automation execution events must include callback receipt and latency metrics.
  • Governance audits must capture subscription, delivery, verification, and automation decision lifecycle events.

5. Acceptance Criteria (OST-00274)#

OST-00274 is complete only when:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for subscription lifecycle, delivery/verification, automation requests/execution, and governance audits are documented.
  4. Ownership boundaries and validation rules are explicit.