[Phase 5.3] Async notifications: outbound webhook

[frankbria]

Goal

Allow users to configure a webhook URL that receives JSON payloads on key CodeFRAME events, enabling integration with Slack, Discord, or any HTTP endpoint.

Background

Browser notifications (issue #559) require the tab to be open at least once. Webhooks are the push-based alternative for headless/automated workflows and CI integrations.

Scope

Settings UI (add to Settings page from #554):

• Webhook URL field in a "Notifications" settings tab (or within existing tabs)
• [Test] button that fires a sample payload and shows status code
• Enable/disable toggle without clearing the URL

Backend:

• Store webhook URL in settings (encrypted at rest)
• Fire POST {webhook_url} with JSON payload on three events:
  • batch complete: { "event": "batch.completed", "batch_id": "...", "task_count": N, "timestamp": "..." }
  • blocker created: { "event": "blocker.created", "blocker_id": "...", "task_id": "...", "timestamp": "..." }
  • PR merged: { "event": "pr.merged", "pr_url": "...", "timestamp": "..." }
• Fire and forget (no retry), log failures to app logger
• 5-second timeout per request

Out of scope

• Webhook signing / HMAC verification (can be added later)
• More than 3 event types in v1

Acceptance criteria

• Webhook URL saves and persists
• [Test] button fires a test payload and shows HTTP status
• Batch completion event fires the webhook
• Failures are logged but do not break the triggering operation
• npm test and uv run pytest pass for the new backend code

[coderabbitai]

🔗 Related PRs

#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase has a clear v2 architecture: a FastAPI backend (codeframe/ui/server.py) with routers in codeframe/ui/routers/, a Next.js frontend (web-ui/) using axios via web-ui/src/lib/api.ts, and a headless core in codeframe/core/. An existing WebhookNotificationService in codeframe/notifications/webhook.py already handles blocker notifications using aiohttp (fire-and-forget, 5s timeout). Batch completion events are emitted via events.emit_for_workspace in codeframe/core/conductor.py at multiple completion points. The workspace SQLite DB (codeframe/core/workspace.py) is the right place to persist webhook settings. No settings router or settings page exists yet.

Approach

Extend the existing WebhookNotificationService with new event-specific methods, add a workspace_settings table to the workspace DB, create a settings_v2 FastAPI router, and add a Notifications settings section to the web-ui. Hook the webhook dispatch into the three trigger points (batch completion in conductor.py, blocker creation in blockers.py, PR merge in pr_v2.py) using the same fire-and-forget pattern already established.

---

Implementation Plan

1. Database: Add workspace_settings table

In file:codeframe/core/workspace.py, add a new workspace_settings table to _init_database and _ensure_schema_upgrades:

CREATE TABLE IF NOT EXISTS workspace_settings (
    key   TEXT NOT NULL,
    value TEXT,
    workspace_id TEXT NOT NULL REFERENCES workspace(id),
    PRIMARY KEY (workspace_id, key)
)

Add two helper functions to workspace.py:

• get_setting(workspace, key) -> Optional[str] — reads a single key
• set_setting(workspace, key, value: Optional[str]) -> None — upserts a key

The webhook URL is stored under key "webhook_url" and the enabled flag under "webhook_enabled" (value "1" / "0").

Note on encryption: The ticket mentions "encrypted at rest." Since the workspace DB is a local SQLite file, store the URL as plaintext for v1 (consistent with how BLOCKER_WEBHOOK_URL is handled today via env var). Add a # TODO: encrypt at rest comment.

---

2. Backend: Extend WebhookNotificationService

In file:codeframe/notifications/webhook.py, add three new methods alongside the existing send_blocker_notification:

• format_batch_payload(batch_id, task_count, timestamp) -> dict — returns {"event": "batch.completed", "batch_id": ..., "task_count": ..., "timestamp": ...}
• format_blocker_payload(blocker_id, task_id, timestamp) -> dict — returns {"event": "blocker.created", "blocker_id": ..., "task_id": ..., "timestamp": ...}
• format_pr_payload(pr_url, timestamp) -> dict — returns {"event": "pr.merged", "pr_url": ..., "timestamp": ...}
• send_event(payload: dict) -> bool — generic async POST method (reuse the existing aiohttp pattern with 5s timeout, fire-and-forget, log failures)
• send_event_background(payload: dict) -> None — wraps send_event with asyncio.create_task

The existing send_blocker_notification can be refactored to call send_event internally.

---

3. Backend: Settings router

Create file:codeframe/ui/routers/settings_v2.py following the pattern of file:codeframe/ui/routers/batches_v2.py:

GET  /api/v2/settings/notifications   → returns { webhook_url, webhook_enabled }
PUT  /api/v2/settings/notifications   → body { webhook_url, webhook_enabled }; saves to DB
POST /api/v2/settings/notifications/test → fires a test payload, returns { status_code, ok }

Pydantic models:

• NotificationSettingsResponse(webhook_url: Optional[str], webhook_enabled: bool)
• UpdateNotificationSettingsRequest(webhook_url: Optional[str], webhook_enabled: bool)
• TestWebhookResponse(status_code: int, ok: bool, error: Optional[str])

The GET reads from get_setting(workspace, "webhook_url") and get_setting(workspace, "webhook_enabled").

The PUT calls set_setting for both keys.

The POST /test instantiates WebhookNotificationService with the stored URL, calls send_event with a test payload {"event": "test", "timestamp": "..."}, and returns the HTTP status code. If the URL is not set or disabled, return 400.

Register the router in file:codeframe/ui/server.py:

from codeframe.ui.routers import settings_v2
app.include_router(settings_v2.router)  # /api/v2/settings

---

4. Backend: Hook webhook into batch completion

In file:codeframe/core/conductor.py, after each events.emit_for_workspace(... EventType.BATCH_COMPLETED ...) call (there are three locations: _execute_serial, _execute_parallel, and _execute_retries), add a webhook dispatch:

• Load the webhook URL and enabled flag via get_setting(workspace, "webhook_url") and get_setting(workspace, "webhook_enabled")
• If enabled, instantiate WebhookNotificationService and call send_event_background with the batch.completed payload
• Wrap in try/except Exception so failures never break the batch

Only fire on BATCH_COMPLETED (not PARTIAL, FAILED, or CANCELLED) to match the ticket scope.

---

5. Backend: Hook webhook into blocker creation

In file:codeframe/core/blockers.py, in the create() function, after events.emit_for_workspace(... BLOCKER_CREATED ...):

• Load webhook settings from get_setting
• If enabled, call send_event_background with the blocker.created payload
• Wrap in try/except

The existing WebhookNotificationService.send_blocker_notification_background in the legacy agents is separate and targets the old BLOCKER_WEBHOOK_URL env var. The new path uses the DB-stored URL.

---

6. Backend: Hook webhook into PR merge

In file:codeframe/ui/routers/pr_v2.py, in the merge_pull_request endpoint, after a successful merge result:

• Load webhook settings from get_setting(workspace, ...)
• If enabled, instantiate WebhookNotificationService and call send_event_background with the pr.merged payload (pr_url from result or the PR details)
• Wrap in try/except

---

7. Frontend: API client additions

In file:web-ui/src/lib/api.ts, add a settingsApi object following the existing pattern:

• getNotifications(workspacePath) → GET /api/v2/settings/notifications
• updateNotifications(workspacePath, data) → PUT /api/v2/settings/notifications
• testWebhook(workspacePath) → POST /api/v2/settings/notifications/test

Add the corresponding TypeScript types to web-ui/src/types/ (or inline in the api file, consistent with how other types are handled).

---

8. Frontend: Settings page and Notifications UI

The web-ui/src/__tests__/components/layout/PipelineProgressBar.test.tsx already references /settings, confirming a settings route is expected.

Create web-ui/src/app/settings/page.tsx — a Next.js page component. Use @radix-ui/react-tabs (already in package.json) to render a tabbed settings layout. Add a "Notifications" tab.

Create web-ui/src/components/settings/NotificationsSettings.tsx — the notifications panel:

┌─────────────────────────────────────────────────────┐
│  Notifications                                       │
│                                                      │
│  Webhook URL                                         │
│  ┌──────────────────────────────────────┐  [Test]   │
│  │ https://hooks.slack.com/...          │           │
│  └──────────────────────────────────────┘           │
│                                                      │
│  ○ Enable webhook notifications                      │
│                                                      │
│  Events: batch complete, blocker created, PR merged  │
└─────────────────────────────────────────────────────┘

Component behavior:

• On mount, call settingsApi.getNotifications(workspacePath) to populate the URL field and toggle state
• The URL input is a controlled <input type="url"> field
• The enable/disable toggle uses @radix-ui/react-checkbox (already in package.json)
• Save: call settingsApi.updateNotifications on blur or an explicit Save button; show success/error via sonner toast (already in package.json)
• [Test] button: calls settingsApi.testWebhook, shows the returned HTTP status code in a sonner toast (e.g., "✓ 200 OK" or "✗ 500 Internal Server Error")
• The [Test] button is disabled when the URL is empty or the toggle is off

Use axios for requests (consistent with the rest of api.ts) and swr for data fetching (already used in the project).

---

Data flow summary

sequenceDiagram
    participant UI as Web UI (Settings)
    participant API as FastAPI /api/v2/settings
    participant DB as workspace_settings (SQLite)
    participant Core as conductor / blockers / pr_v2
    participant WH as WebhookNotificationService
    participant Ext as External Webhook URL

    UI->>API: PUT /api/v2/settings/notifications
    API->>DB: set_setting(webhook_url, webhook_enabled)

    UI->>API: POST /api/v2/settings/notifications/test
    API->>WH: send_event({event: "test", ...})
    WH->>Ext: POST webhook_url
    Ext-->>WH: 200 OK
    WH-->>API: status_code=200
    API-->>UI: {status_code: 200, ok: true}

    Core->>DB: get_setting(webhook_url)
    Core->>WH: send_event_background({event: "batch.completed", ...})
    WH-->>Ext: POST webhook_url (fire-and-forget)

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clear v2 architecture: a FastAPI backend (`codeframe/ui/server.py`) with routers in `codeframe/ui/routers/`, a Next.js frontend (`web-ui/`) using `axios` via `web-ui/src/lib/api.ts`, and a headless core in `codeframe/core/`. An existing `WebhookNotificationService` in `codeframe/notifications/webhook.py` already handles blocker notifications using `aiohttp` (fire-and-forget, 5s timeout). Batch completion events are emitted via `events.emit_for_workspace` in `codeframe/core/conductor.py` at multiple completion points. The workspace SQLite DB (`codeframe/core/workspace.py`) is the right place to persist webhook settings. No settings router or settings page exists yet.

## Approach

Extend the existing `WebhookNotificationService` with new event-specific methods, add a `workspace_settings` table to the workspace DB, create a `settings_v2` FastAPI router, and add a Notifications settings section to the web-ui. Hook the webhook dispatch into the three trigger points (batch completion in `conductor.py`, blocker creation in `blockers.py`, PR merge in `pr_v2.py`) using the same fire-and-forget pattern already established.

---

## Implementation Plan

### 1. Database: Add `workspace_settings` table

In `file:codeframe/core/workspace.py`, add a new `workspace_settings` table to `_init_database` and `_ensure_schema_upgrades`:

```sql
CREATE TABLE IF NOT EXISTS workspace_settings (
    key   TEXT NOT NULL,
    value TEXT,
    workspace_id TEXT NOT NULL REFERENCES workspace(id),
    PRIMARY KEY (workspace_id, key)
)
```

Add two helper functions to `workspace.py`:
- `get_setting(workspace, key) -> Optional[str]` — reads a single key
- `set_setting(workspace, key, value: Optional[str]) -> None` — upserts a key

The webhook URL is stored under key `"webhook_url"` and the enabled flag under `"webhook_enabled"` (value `"1"` / `"0"`).

> **Note on encryption**: The ticket mentions "encrypted at rest." Since the workspace DB is a local SQLite file, store the URL as plaintext for v1 (consistent with how `BLOCKER_WEBHOOK_URL` is handled today via env var). Add a `# TODO: encrypt at rest` comment.

---

### 2. Backend: Extend `WebhookNotificationService`

In `file:codeframe/notifications/webhook.py`, add three new methods alongside the existing `send_blocker_notification`:

- **`format_batch_payload(batch_id, task_count, timestamp) -> dict`** — returns `{"event": "batch.completed", "batch_id": ..., "task_count": ..., "timestamp": ...}`
- **`format_blocker_payload(blocker_id, task_id, timestamp) -> dict`** — returns `{"event": "blocker.created", "blocker_id": ..., "task_id": ..., "timestamp": ...}`
- **`format_pr_payload(pr_url, timestamp) -> dict`** — returns `{"event": "pr.merged", "pr_url": ..., "timestamp": ...}`
- **`send_event(payload: dict) -> bool`** — generic async POST method (reuse the existing `aiohttp` pattern with 5s timeout, fire-and-forget, log failures)
- **`send_event_background(payload: dict) -> None`** — wraps `send_event` with `asyncio.create_task`

The existing `send_blocker_notification` can be refactored to call `send_event` internally.

---

### 3. Backend: Settings router

Create `file:codeframe/ui/routers/settings_v2.py` following the pattern of `file:codeframe/ui/routers/batches_v2.py`:

```
GET  /api/v2/settings/notifications   → returns { webhook_url, webhook_enabled }
PUT  /api/v2/settings/notifications   → body { webhook_url, webhook_enabled }; saves to DB
POST /api/v2/settings/notifications/test → fires a test payload, returns { status_code, ok }
```

Pydantic models:
- `NotificationSettingsResponse(webhook_url: Optional[str], webhook_enabled: bool)`
- `UpdateNotificationSettingsRequest(webhook_url: Optional[str], webhook_enabled: bool)`
- `TestWebhookResponse(status_code: int, ok: bool, error: Optional[str])`

The `GET` reads from `get_setting(workspace, "webhook_url")` and `get_setting(workspace, "webhook_enabled")`.

The `PUT` calls `set_setting` for both keys.

The `POST /test` instantiates `WebhookNotificationService` with the stored URL, calls `send_event` with a test payload `{"event": "test", "timestamp": "..."}`, and returns the HTTP status code. If the URL is not set or disabled, return 400.

Register the router in `file:codeframe/ui/server.py`:
```python
from codeframe.ui.routers import settings_v2
app.include_router(settings_v2.router)  # /api/v2/settings
```

---

### 4. Backend: Hook webhook into batch completion

In `file:codeframe/core/conductor.py`, after each `events.emit_for_workspace(... EventType.BATCH_COMPLETED ...)` call (there are three locations: `_execute_serial`, `_execute_parallel`, and `_execute_retries`), add a webhook dispatch:

- Load the webhook URL and enabled flag via `get_setting(workspace, "webhook_url")` and `get_setting(workspace, "webhook_enabled")`
- If enabled, instantiate `WebhookNotificationService` and call `send_event_background` with the `batch.completed` payload
- Wrap in `try/except Exception` so failures never break the batch

Only fire on `BATCH_COMPLETED` (not `PARTIAL`, `FAILED`, or `CANCELLED`) to match the ticket scope.

---

### 5. Backend: Hook webhook into blocker creation

In `file:codeframe/core/blockers.py`, in the `create()` function, after `events.emit_for_workspace(... BLOCKER_CREATED ...)`:

- Load webhook settings from `get_setting`
- If enabled, call `send_event_background` with the `blocker.created` payload
- Wrap in `try/except`

> The existing `WebhookNotificationService.send_blocker_notification_background` in the legacy agents is separate and targets the old `BLOCKER_WEBHOOK_URL` env var. The new path uses the DB-stored URL.

---

### 6. Backend: Hook webhook into PR merge

In `file:codeframe/ui/routers/pr_v2.py`, in the `merge_pull_request` endpoint, after a successful merge result:

- Load webhook settings from `get_setting(workspace, ...)`
- If enabled, instantiate `WebhookNotificationService` and call `send_event_background` with the `pr.merged` payload (`pr_url` from `result` or the PR details)
- Wrap in `try/except`

---

### 7. Frontend: API client additions

In `file:web-ui/src/lib/api.ts`, add a `settingsApi` object following the existing pattern:

- `getNotifications(workspacePath)` → `GET /api/v2/settings/notifications`
- `updateNotifications(workspacePath, data)` → `PUT /api/v2/settings/notifications`
- `testWebhook(workspacePath)` → `POST /api/v2/settings/notifications/test`

Add the corresponding TypeScript types to `web-ui/src/types/` (or inline in the api file, consistent with how other types are handled).

---

### 8. Frontend: Settings page and Notifications UI

The `web-ui/src/__tests__/components/layout/PipelineProgressBar.test.tsx` already references `/settings`, confirming a settings route is expected.

**Create `web-ui/src/app/settings/page.tsx`** — a Next.js page component. Use `@radix-ui/react-tabs` (already in `package.json`) to render a tabbed settings layout. Add a "Notifications" tab.

**Create `web-ui/src/components/settings/NotificationsSettings.tsx`** — the notifications panel:

```
┌─────────────────────────────────────────────────────┐
│  Notifications                                       │
│                                                      │
│  Webhook URL                                         │
│  ┌──────────────────────────────────────┐  [Test]   │
│  │ https://hooks.slack.com/...          │           │
│  └──────────────────────────────────────┘           │
│                                                      │
│  ○ Enable webhook notifications                      │
│                                                      │
│  Events: batch complete, blocker created, PR merged  │
└─────────────────────────────────────────────────────┘
```

Component behavior:
- On mount, call `settingsApi.getNotifications(workspacePath)` to populate the URL field and toggle state
- The URL input is a controlled `<input type="url">` field
- The enable/disable toggle uses `@radix-ui/react-checkbox` (already in `package.json`)
- **Save**: call `settingsApi.updateNotifications` on blur or an explicit Save button; show success/error via `sonner` toast (already in `package.json`)
- **[Test] button**: calls `settingsApi.testWebhook`, shows the returned HTTP status code in a `sonner` toast (e.g., "✓ 200 OK" or "✗ 500 Internal Server Error")
- The [Test] button is disabled when the URL is empty or the toggle is off

Use `axios` for requests (consistent with the rest of `api.ts`) and `swr` for data fetching (already used in the project).

---

### Data flow summary

```mermaid
sequenceDiagram
    participant UI as Web UI (Settings)
    participant API as FastAPI /api/v2/settings
    participant DB as workspace_settings (SQLite)
    participant Core as conductor / blockers / pr_v2
    participant WH as WebhookNotificationService
    participant Ext as External Webhook URL

    UI->>API: PUT /api/v2/settings/notifications
    API->>DB: set_setting(webhook_url, webhook_enabled)

    UI->>API: POST /api/v2/settings/notifications/test
    API->>WH: send_event({event: "test", ...})
    WH->>Ext: POST webhook_url
    Ext-->>WH: 200 OK
    WH-->>API: status_code=200
    API-->>UI: {status_code: 200, ok: true}

    Core->>DB: get_setting(webhook_url)
    Core->>WH: send_event_background({event: "batch.completed", ...})
    WH-->>Ext: POST webhook_url (fire-and-forget)
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.