# ADR-0047: OSHUN Studio Webhooks and External Automation

**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.

## Related Decisions

- `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`