Integrations and Webhooks — SPEC

Start here → AGENTS.md · SPEC_INDEX.md · SECURITY.md.

Metadata

Evidence Rules

Current routes, shared adapters, stores/components, and tests define behavior. Prior OAuth/my-integrations/webhook specs were mapped to current operations, state, validation, and failure paths.

Source Material Register

Overview

This module supports native integration connection, the authenticated My Integrations page, authorization removal, and webhook listing/creation/deletion. The browser uses same-origin APIs and Nano Stores; route handlers acquire server session tokens and call the Hydra/Webex adapter layer.

Purpose / Responsibility

Owns user-visible integration and webhook lifecycle orchestration; upstream services remain the system-of-record.

Stack

Astro endpoints/pages, React islands, Nano Stores, Hydra/Webex adapters, secure cookies, Vitest.

Folder / Package Structure

src/pages/
├── integration/[integrationId]/connect.ts
├── integration/auth.ts
├── my-integrations.astro
└── api/{my-integrations,my-webhooks,webhooks,remove-authorization}.ts
src/components/{MyIntegrations,Webhooks,WebhookConnectButton,WebhookAppGate}.tsx
src/stores/{myIntegrations,authorizations,webhooks}Store.ts

Key Files (source of truth)

Public Surface

Requires (dependencies)

Authenticated server session, Hydra/Webex APIs, adapter types/validation constants, CSRF middleware/client helper, safe URL helpers, integration/webhook stores and notifications.

Requirements

Design Overview

Native integration OAuth uses short-lived cookies separate from the main login state. Management routes use the main server session and adapter facade. React components coordinate stores and same-origin API calls; successful mutations update lists and notifications without owning upstream persistence.

Data Flow

flowchart LR
  UI --> ClientApi["same-origin API"]
  ClientApi --> Auth["requireAuth"]
  Auth --> Service["DataService/Hydra client"]
  Service --> Webex
  Webex --> Service --> APIResponse --> Stores --> UI
  UI --> Connect --> CI["integration OAuth"] --> Callback --> UI

Sequence Diagram(s)

sequenceDiagram
  participant U as User
  participant UI as Management UI
  participant A as App Hub API
  participant W as Webex
  U->>UI: create/delete/disconnect
  UI->>A: same-origin request + CSRF
  A->>A: requireAuth + validate
  A->>W: authorized mutation
  alt success
    W-->>A: result
    A-->>UI: 201/204/200
    UI->>UI: update store + success notification
  else failure
    W-->>A: error
    A-->>UI: stable error status
    UI->>UI: preserve list + error notification
  end

sequenceDiagram
  participant U as User
  participant C as Connect route
  participant I as Identity provider
  participant A as Callback route
  U->>C: navigate /integration/:id/connect
  C->>C: validate id/scopes/navigation/session/return
  C-->>I: state cookies + 302 authorize
  I-->>A: code or denial + state
  A->>A: clear cookies + compare state + exchange
  A-->>U: 302 safe return with result query

sequenceDiagram
  participant UI as My Integrations UI
  participant A as List API
  participant S as DataService
  UI->>A: GET integration/webhook list
  A->>A: requireAuth
  alt authenticated
    A->>S: fetch and validate items
    S-->>A: items
    A-->>UI: JSON list
  else invalid session/upstream
    A-->>UI: stable error
  end

Class / Component Relationships

classDiagram
  class MyIntegrations
  class Webhooks
  class IntegrationRoutes
  class ApiRoutes
  class NanoStores
  class DataService
  MyIntegrations --> NanoStores
  Webhooks --> NanoStores
  MyIntegrations --> ApiRoutes
  Webhooks --> ApiRoutes
  ApiRoutes --> DataService
  IntegrationRoutes --> DataService

Use Cases

• UC-1 Connect native integration: authenticated user navigates to connect → stateful OAuth → success/denial result on safe page. Evidence: src/pages/integration/[integrationId]/connect.ts, src/pages/integration/auth.ts.
• UC-2 Disconnect integration: user confirms → authenticated DELETE → list removes item only on success. Evidence: src/pages/api/remove-authorization.ts, src/stores/authorizationsStore.ts.
• UC-3 Manage webhook: load list → validate form → create/delete → update store and notification. Evidence: src/pages/api/webhooks.ts, src/components/Webhooks.tsx, src/stores/webhooksStore.ts.

State Model

myIntegrationsStore, authorizationsStore, and webhooksStore keep separate list/loading/error and mutation-loading/error fields. OAuth completion communicates transient result through safe query parameters rather than browser token state.

Business Rules & Invariants

• Upstream is system-of-record; local list changes follow successful upstream responses.
• Webhook names/types obey constants in src/lib/adapters/types.ts.
• Temporary OAuth cookies are cleared on callback.
• Mutations are authenticated and CSRF protected.

Concurrency & Reactive Flow

• List fetches and mutations are async; stores prevent a shared generic error from hiding operation-specific failures.
• The UI should disable duplicate in-flight mutations.
• Concurrent server instances share user sessions through Redis.

State Machine

stateDiagram-v2
  [*] --> Loading
  Loading --> Ready: list success
  Loading --> Error: list failure
  Ready --> Mutating: add/delete/disconnect
  Mutating --> Ready: success + list update
  Mutating --> Error: failure + list preserved
  Error --> Loading: retry

UI Flow

• Auth gate → loading → empty or populated integrations/webhooks.
• Connect uses full-page navigation; callback returns success/denial/error query state.
• Mutations show pending state, retain current list on failure, and produce accessible notification feedback.

Error Handling & Failure Modes

Pitfalls

• Native integration OAuth is separate from App Hub login and uses distinct cookies.
• A GET connect endpoint is guarded as navigation; converting it to fetch semantics changes CSRF posture.
• Optimistically removing an item before success can misrepresent upstream state.

Module Do’s / Don’ts

• DO use requireAuth(), shared adapters, body-size checks, and client API helpers.
• DO clear temporary cookies on every callback path.
• DON’T place integration tokens in Nano Stores/URLs.
• DON’T add external browser calls.

Key Design Trade-off

Same-origin management APIs and server sessions add an application hop, but keep credentials out of the browser and centralize validation/observability.

Test-Case Strategy (module)

Cover OAuth success/denial/bad state/navigation/return paths; list auth/schema failures; webhook body/type/name/status paths; store success/error/reset; and representative authenticated E2E when environment credentials exist.

Traceability

• Security: SECURITY.md
• Contracts: CONTRACTS.md
• Coverage baseline: .sdd/manifest.json