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.mddocs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.mddocs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.mddocs/adr/ADR-0047-oshun-studio-webhooks-and-external-automation.mdapps/iris/developer-portal/src/services/webhook-management-service.tsapps/iris/api/src/docs/index.tsapps/psyche/admin/src/api/client.tsapps/isis/cli/src/commands/generate.tsapps/bellona/build-api/src/main.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/runbooks/on-call-runbook.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for subscription lifecycle, delivery/verification, automation requests/execution, and governance audits are documented.
- Ownership boundaries and validation rules are explicit.