Merge pull request #35 from markrai/feature/webhooks

Feature/webhooks (phase 1)

Author: markrai

CHANGELOG.md

@@ -1,8 +1,27 @@
 # Changelog
 
-> **Upgrades:** No breaking changes in **3.7.x** / **3.8.x** / **3.9.x** unless noted below.
+> **Upgrades:** No breaking changes in **3.7.x** / **3.8.x** / **3.9.x** / **3.10.x** unless noted below.
 
 
+## [3.10.0] - 2026-04-04
+
+### Features
+
+- **Event bus + SSE** — **`internal/eventbus`** fanout; **`PublishEvent`** on the server. Board refresh / members events go through the bus; **`sseBridge`** keeps the same SSE JSON as before.
+- **`todo.assigned`** — Published after commit from **`CreateTodo`** / **`UpdateTodo`** when assignee changes (non-anonymous temp boards). SSE uses reason **`todo_assigned`**; handlers skip duplicate **`todo_created`** / **`todo_updated`** refresh when **`AssignmentChanged`**.
+- **Webhooks (full mode)** — **`POST` / `GET` / `DELETE`** **`/api/webhooks`** (maintainer, session; **404** in anonymous mode). Migration **050**; optional HMAC **`X-Scrumboy-Signature`**; async queue + worker, retries, JSON envelope with event **`id`** (for idempotency). Dispatcher enqueues in a goroutine with a detached context so SSE is not blocked.
+
+### Fixes
+
+- **Shutdown** — HTTP **`Shutdown`** before cancelling the webhook worker.
+- **CreateTodo** — Same **`!isAnonymousBoard`** gate as **`UpdateTodo`** for assignment events.
+
+### Other
+
+- Tests: **`eventbus_regression_test.go`**. Docs: README webhooks section + TOC. Dep: **`github.com/google/uuid`**.
+
+---
+
 ## [3.9.4] - 2026-04-04
 
 ### Fixes

README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <img width="372" src="internal/httpapi/web/githublogo.png" alt="scrumboy logo" />
   <br />
-  <img src="https://img.shields.io/badge/version-v3.9.4-blue" alt="version" />
+  <img src="https://img.shields.io/badge/version-v3.10.0-blue" alt="version" />
   <a href="LICENSE">
     <img src="https://img.shields.io/badge/license-AGPL--v3-orange" alt="license" />
   </a>
@@ -12,6 +12,34 @@
 
 <img width="2975" height="1078" alt="image" src="internal/httpapi/web/github_preview.jpg" />
 
+## Table of contents
+
+- [Quick Start](#quick-start)
+  - [Run with Docker](#run-with-docker)
+  - [Run from source](#run-from-source)
+- [Optional Configuration](#optional-configuration)
+  - [Environment variables](#environment-variables)
+  - [Encryption key (optional)](#encryption-key-optional)
+  - [OIDC / SSO login (optional)](#oidc--sso-login-optional)
+  - [TLS / HTTPS (optional)](#tls--https-optional)
+  - [Frontend build note](#frontend-build-note)
+- [Why Scrumboy?](#why-scrumboy)
+- [Who is this for?](#who-is-this-for)
+- [Modes](#modes)
+- [Features](#features)
+- [Integrations & API Access](#integrations--api-access)
+  - [MCP (JSON-RPC) for AI agents](#mcp-json-rpc-for-ai-agents)
+  - [Webhooks (outbound HTTP)](#webhooks-outbound-http)
+- [Config](#config)
+- [Roles](#roles)
+  - [System roles (instance-wide)](#system-roles-instance-wide)
+  - [Project roles (per project)](#project-roles-per-project)
+- [Export scope](#export-scope)
+- [Import modes](#import-modes)
+- [Code layout (reference)](#code-layout-reference)
+- [Documentation](#documentation)
+- [License and Contributions](#license-and-contributions)
+
 ## Quick Start
 
 Runs in seconds. No setup required.
@@ -117,6 +145,8 @@ Simplicity of a light Kanban, with the power of structured systems: Roles, sprin
 
 - Realtime SSE enabled boards for instant multi-user actions.
 
+- **Webhooks (API-only, full mode):** Register URLs per project so Scrumboy can POST JSON when subscribed domain events fire (e.g. `todo.assigned`). For your own automations—not in-app or browser notifications. See [Integrations](#integrations--api-access).
+
 - Customizable Tags: Users can inherit and customize tag colors.
 
 - Advanced filtering: Search todos based on text or tags.
@@ -218,6 +248,26 @@ This enables:
 - AI agents and MCP clients (use **`POST /mcp/rpc`** for JSON-RPC; **`POST /mcp`** remains available for the legacy `{ "tool", "input" }` envelope)
 - Scripting/integrations without login flows
 
+### Webhooks (outbound HTTP)
+
+Scrumboy can **POST JSON to URLs you register** when certain events occur. This is for **server-side integrations** (your script, gateway, queue worker, etc.). It does **not** add notifications inside the Scrumboy UI; live boards still update via **SSE** as before.
+
+- **Availability:** **Full mode only** (endpoints are disabled in anonymous mode).
+- **Who can configure:** Project **maintainers**, via the HTTP API only—there is **no settings screen** for webhooks yet.
+- **API:** `POST /api/webhooks` (create), `GET /api/webhooks` (list yours), `DELETE /api/webhooks/{id}` — same session cookie / CSRF header rules as other mutating `/api/*` calls.
+- **Events:** Subscribe to specific types (e.g. `todo.assigned`) or `*` for all delivered types. The set may grow over time; unused types in your list are harmless.
+- **Security:** Optional per-webhook **secret**; when set, requests include an `X-Scrumboy-Signature` header (`sha256=` HMAC of the raw JSON body).
+- **Semantics:** Best-effort delivery with retries on failure; not a durable external queue—design for idempotent receivers using the event `id` in the JSON body.
+
+Example create (replace cookie / project id / URL):
+
+```bash
+curl -b cookies.txt -X POST http://localhost:8080/api/webhooks \
+  -H "Content-Type: application/json" \
+  -H "X-Scrumboy: 1" \
+  -d '{"projectId":1,"url":"https://example.com/scrumboy-hook","events":["todo.assigned"],"secret":"optional-shared-secret"}'
+```
+
 
 # Config
 

cmd/scrumboy/main.go

@@ -94,6 +94,7 @@ func main() {
 		EncryptionKey:  encKey,
 		OIDCService:    oidcSvc,
 	})
+	st.SetTodoAssignedPublisher(srv.PublishTodoAssigned)
 
 	httpServer := &http.Server{
 		Addr:              cfg.BindAddr,
@@ -177,9 +178,12 @@ func main() {
 
 	<-stop
 
+	// Drain in-flight HTTP requests first so any final todo.assigned events
+	// are published and enqueued before the webhook worker is stopped.
 	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer shutdownCancel()
 	if err := httpServer.Shutdown(shutdownCtx); err != nil {
 		logger.Printf("shutdown: %v", err)
 	}
+	srv.Close()
 }

go.mod

@@ -7,6 +7,7 @@ toolchain go1.25.5
 require (
 	github.com/coreos/go-oidc/v3 v3.11.0
 	github.com/go-jose/go-jose/v4 v4.0.2
+	github.com/google/uuid v1.6.0
 	github.com/pquerna/otp v1.5.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	golang.org/x/crypto v0.25.0
@@ -17,7 +18,6 @@ require (
 require (
 	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v0.1.9 // indirect

internal/eventbus/event.go

@@ -0,0 +1,26 @@
+package eventbus
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+)
+
+// Event is the canonical domain event passed through the bus.
+type Event struct {
+	ID        string          `json:"id"`
+	Type      string          `json:"type"`
+	Time      time.Time       `json:"timestamp"`
+	ProjectID int64           `json:"projectId"`
+	Payload   json.RawMessage `json:"payload,omitempty"`
+}
+
+// Consumer receives events from the bus.
+type Consumer interface {
+	OnEvent(ctx context.Context, e Event)
+}
+
+// Publisher sends events into the bus.
+type Publisher interface {
+	Publish(ctx context.Context, e Event) error
+}

internal/eventbus/fanout.go

@@ -0,0 +1,30 @@
+package eventbus
+
+import (
+	"context"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// Fanout distributes each published event to all registered consumers in order.
+type Fanout struct {
+	consumers []Consumer
+}
+
+func NewFanout(consumers ...Consumer) *Fanout {
+	return &Fanout{consumers: consumers}
+}
+
+func (f *Fanout) Publish(ctx context.Context, e Event) error {
+	if e.ID == "" {
+		e.ID = uuid.NewString()
+	}
+	if e.Time.IsZero() {
+		e.Time = time.Now().UTC()
+	}
+	for _, c := range f.consumers {
+		c.OnEvent(ctx, e)
+	}
+	return nil
+}