Disciplines · Decisions (ADRs)

ADR-0047: OSHUN Studio Webhooks and External Automation

Studio workflows increasingly depend on external systems for CI/CD automation, incident workflows, approvals, and partner ecosystem integrations.

Accepted · 2026-02-23
10sections3 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN BFF Engineering, OSHUN Security Engineering, Platform SRE
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design, Compliance

Context and Problem Statement#

Studio workflows increasingly depend on external systems for CI/CD automation, incident workflows, approvals, and partner ecosystem integrations. Event export and callback capabilities exist in parts of the ecosystem, but Studio-level webhook and automation governance is not yet standardized.

Without a canonical webhook/automation model, Studio risks:

  • fragmented event contracts and inconsistent delivery behavior
  • weak verification and security posture for outbound callbacks
  • duplicate automation logic across domains and tools
  • poor observability for automation failures and retries

Decision Drivers#

  • Consistency: one webhook contract model across Studio workflows.
  • Security: strict signing, verification, and secret lifecycle controls.
  • Reliability: deterministic retries, idempotency, and failure handling.
  • Operability: clear telemetry/audit signals and on-call playbooks.
  • Extensibility: safe automation for internal and external integrations.

Considered Options#

Option 1: Domain-Local Webhooks and Automation#

Each domain defines independent webhook payloads, signing behavior, and retries.

Pros:

  • High domain autonomy.

Cons:

  • Contract drift and inconsistent security posture.
  • Difficult cross-domain automation governance and observability.

Option 2: Basic Shared Event Bus Without Automation Governance#

Publish events but leave delivery policy, signing, and retries mostly ad hoc.

Pros:

  • Lower short-term complexity.

Cons:

  • Weak reliability guarantees and opaque delivery behavior.
  • Limited compliance readiness for external automation paths.

Option 3: Canonical Studio Webhook and External Automation Framework (Chosen)#

Adopt typed webhook contracts, policy-aware subscription governance, signed delivery, deterministic retry/idempotency semantics, and telemetry-backed operations.

Pros:

  • Consistent integration behavior and stronger security controls.
  • Better reliability and diagnostics for automation pipelines.
  • Safer expansion into partner and enterprise integration use cases.

Cons:

  • Requires lifecycle governance for event versions and subscriber contracts.

Decision Outcome#

Chosen option: Option 3.

Webhook and external automation requirements:

  1. Canonical event/subscription contracts with versioning semantics.
  2. Security controls for signature verification and secret rotation.
  3. Deterministic delivery lifecycle with retry/backoff/idempotency rules.
  4. Policy-aware governance for privileged automation actions.
  5. Telemetry/audit contracts for delivery and automation accountability.

Normative Rules#

Event and Subscription Contract Rule#

  • Webhook events must be schema-versioned and domain-attributed.
  • Subscriptions require owner, scope, destination, and secret metadata.
  • Breaking event changes require explicit version migration paths.

Security and Verification Rule#

  • Outbound webhook payloads must be signed with managed secrets.
  • Receiver verification metadata must be deterministic and documented.
  • Secret rotation and revocation must be auditable and policy-enforced.

Delivery and Idempotency Rule#

  • Delivery must use bounded retry/backoff with deterministic terminal states.
  • Idempotency keys are required for retry-safe automation handlers.
  • Failed deliveries beyond retry budget must create operator-visible incidents.

Automation and Governance Rule#

  • Sensitive automation actions require role/tier/approval checks.
  • Automation decisions must emit reason-coded audit events.
  • Release promotions must block on unresolved critical automation failures.

Architecture Implications#

  • Studio webhook management surfaces become first-class governance modules.
  • BFF and automation services own canonical subscription and delivery orchestration boundaries.
  • Domain emitters for Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian align to shared webhook contracts.
  • Observability dashboards incorporate delivery success, retry, and lag SLOs.

Acceptance Criteria (OST-00273)#

OST-00273 is complete only when:

  1. ADR exists at docs/adr/ADR-0053-oshun-studio-webhooks-and-external-automation.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines event/subscription, security, delivery/idempotency, and automation/governance rules.
  4. ADR aligns with ADR-0007 through ADR-0046, especially ADR-0007, ADR-0012, ADR-0041, and ADR-0046.
  5. ADR aligns with existing webhook/automation implementation surfaces.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Stronger webhook security and delivery reliability posture.
  • Consistent external automation integration across Studio workflows.
  • Better operational visibility and incident response for automation failures.

Negative#

  • Increased governance overhead for event and subscription lifecycle changes.
  • Requires coordinated rollout of signing and retry semantics across services.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md
  • docs/adr/ADR-0052-oshun-studio-api-gateway-and-bff-composition.md

References#

  • 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