Eve library

OSHUN Studio Webhooks and External Automation Journeys and Edge Cases

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
  • docs/releases/v1/specs/studio-webhooks-and-external-automation-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and deterministic edge-case behavior for Studio webhooks and external automation workflows.

This document is the execution artifact for OST-00275.

Personas#

  • Integration Operator
  • Program Operator
  • Security Reviewer
  • Compliance Auditor
  • SRE Incident Commander

Journey Principles#

  1. Subscription and event contracts must be versioned and owner-attributed.
  2. Signing, verification, and secret lifecycle controls are mandatory.
  3. Delivery retries and idempotency behavior must remain deterministic.
  4. Sensitive automation actions require role/tier/approval governance.

1. Primary Journeys#

J1. Create and Activate Webhook Subscription#

Goal: Register a secure webhook subscription for Studio automation events.

Entry: Webhooks and external automation workspace

Steps:

  1. Define destination URL, event types, and owner metadata.
  2. Assign domain scope and release-channel constraints.
  3. Generate signing secret and verification metadata.
  4. Validate contract and activate subscription.
  5. Emit subscription-created audit event.

Success State:

  • Subscription is active, signed, and policy-compliant.

J2. Dispatch Signed Event to External Receiver#

Goal: Deliver signed event payload to subscriber endpoint.

Entry: Studio event trigger

Steps:

  1. Build versioned event envelope and idempotency key.
  2. Sign payload with active subscription secret.
  3. Dispatch webhook and capture response latency/status.
  4. Persist delivery attempt result.
  5. Emit delivery telemetry and audit events.

Success State:

  • Event is delivered with verifiable signature and recorded evidence.

J3. Execute Retry and Terminal Failure Handling#

Goal: Recover transient delivery errors without duplicate side effects.

Entry: Initial delivery failure

Steps:

  1. Classify failure as retryable or terminal.
  2. Schedule bounded backoff retry attempts.
  3. Re-send with same idempotency identity.
  4. Mark terminal failure when retry budget is exhausted.
  5. Open incident and notify operator on terminal failure.

Success State:

  • Delivery lifecycle is deterministic and operationally visible.

J4. Decide Sensitive Automation Action#

Goal: Govern privileged automation actions (pause, resume, rotate-secret, production-trigger).

Entry: Sensitive automation request

Steps:

  1. Evaluate actor role, tier, and scope context.
  2. Validate production approval prerequisites where required.
  3. Allow or deny action with explicit reason code.
  4. Persist governance evidence for compliance.
  5. Emit policy decision audit event.

Success State:

  • Sensitive automation is centrally governed and audit-ready.

J5. Recover Automation Health and Close Incident#

Goal: Restore failing webhook/automation path and close incident safely.

Entry: Open delivery or automation incident

Steps:

  1. Correlate delivery failures, receiver health, and policy signals.
  2. Apply mitigation (receiver fix, secret rotation, retry tuning, rollback).
  3. Re-run validation dispatch and automation checks.
  4. Confirm delivery and execution SLO recovery.
  5. Close incident with post-recovery evidence.

Success State:

  • Automation path is healthy with validated recovery evidence.

2. Critical Edge Cases#

E1. Subscription Without Event Types#

  • Trigger: subscription activation requested without events.
  • Required behavior: reject activation with contract validation error.

E2. Invalid Destination URL Scheme#

  • Trigger: destination URL is non-HTTPS for production scope.
  • Required behavior: hard deny and require secure endpoint.

E3. Signature Header Missing on Delivery#

  • Trigger: dispatch occurs without signature metadata.
  • Required behavior: fail delivery and emit verification incident.

E4. Replay Delivery Without Idempotency Key#

  • Trigger: retry path omits idempotency identity.
  • Required behavior: block retry and mark attempt invalid.

E5. Retry Budget Drift#

  • Trigger: retries exceed configured max-attempt policy.
  • Required behavior: terminate delivery and open on-call incident.

E6. Secret Rotation Mid-Delivery Window#

  • Trigger: secret rotated while retries are in flight.
  • Required behavior: preserve compatibility window and audit transition.

E7. Sensitive Action with Unauthorized Tier#

  • Trigger: actor requests secret rotation with insufficient tier.
  • Required behavior: deny action and emit policy-denial audit event.

E8. Production Trigger Without Approval Ticket#

  • Trigger: production automation request missing approval evidence.
  • Required behavior: hard deny and require CAB/reference ticket.

E9. Receiver Returns Persistent 4xx#

  • Trigger: endpoint consistently returns non-retryable 4xx codes.
  • Required behavior: stop retries and flag subscription as failing.

E10. Audit Event Emission Failure#

  • Trigger: delivery/decision succeeds but governance audit cannot persist.
  • Required behavior: mark degraded-observability state and page on-call.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Create/Activate Subscription Subscription governance panel Contract registry + secret management
J2 Dispatch Signed Event Delivery execution panel Signing service + dispatch runtime
J3 Retry and Terminal Failure Handling Delivery lifecycle panel Retry scheduler + incident integration
J4 Decide Sensitive Automation Action Policy decision panel RBAC/tier engine + approval governance
J5 Recover Automation Health Incident recovery panel Telemetry dashboards + remediation controls

4. Instrumentation Requirements#

Required events:

  • webhooks_external_automation.journey.started
  • webhooks_external_automation.journey.step.completed
  • webhooks_external_automation.journey.blocked
  • webhooks_external_automation.journey.retrying
  • webhooks_external_automation.journey.recovered
  • webhooks_external_automation.journey.completed

Required dimensions:

  • subscriptionId, eventId, destinationUrl, eventType, sourceDomain
  • deliveryStatus, retryCount, maxRetries, responseCode, latencyMs
  • idempotencyKey, signatureVersion, actorId, actorRole, permissionTier
  • releaseChannel, approvalTicketRef, journeyId, stepId, outcome, reasonCode

5. Acceptance Criteria (OST-00275)#

OST-00275 is complete only when:

  1. At least five webhook/automation journeys are documented.
  2. At least ten deterministic edge cases are documented.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.