# OSHUN Studio Webhooks and External Automation Dependency and Data Contract Map

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.
