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.mddocs/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#
- Subscription and event contracts must be versioned and owner-attributed.
- Signing, verification, and secret lifecycle controls are mandatory.
- Delivery retries and idempotency behavior must remain deterministic.
- 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:
- Define destination URL, event types, and owner metadata.
- Assign domain scope and release-channel constraints.
- Generate signing secret and verification metadata.
- Validate contract and activate subscription.
- 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:
- Build versioned event envelope and idempotency key.
- Sign payload with active subscription secret.
- Dispatch webhook and capture response latency/status.
- Persist delivery attempt result.
- 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:
- Classify failure as retryable or terminal.
- Schedule bounded backoff retry attempts.
- Re-send with same idempotency identity.
- Mark terminal failure when retry budget is exhausted.
- 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:
- Evaluate actor role, tier, and scope context.
- Validate production approval prerequisites where required.
- Allow or deny action with explicit reason code.
- Persist governance evidence for compliance.
- 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:
- Correlate delivery failures, receiver health, and policy signals.
- Apply mitigation (receiver fix, secret rotation, retry tuning, rollback).
- Re-run validation dispatch and automation checks.
- Confirm delivery and execution SLO recovery.
- 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.startedwebhooks_external_automation.journey.step.completedwebhooks_external_automation.journey.blockedwebhooks_external_automation.journey.retryingwebhooks_external_automation.journey.recoveredwebhooks_external_automation.journey.completed
Required dimensions:
subscriptionId,eventId,destinationUrl,eventType,sourceDomaindeliveryStatus,retryCount,maxRetries,responseCode,latencyMsidempotencyKey,signatureVersion,actorId,actorRole,permissionTierreleaseChannel,approvalTicketRef,journeyId,stepId,outcome,reasonCode
5. Acceptance Criteria (OST-00275)#
OST-00275 is complete only when:
- At least five webhook/automation journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.