From 3312716afd65d4ac8ceb6cabea7e6ed003467052 Mon Sep 17 00:00:00 2001
From: kolaente <k@knt.li>
Date: Thu, 11 Jun 2026 20:41:57 +0200
Subject: [PATCH] feat(api/v2): add available webhook events endpoint

Add GET /api/v2/webhooks/events, listing the events a webhook target can
subscribe to. Gated on webhooks.enabled via a registrar early-return, mirroring
v1.
---
 pkg/routes/api/v2/webhook_events.go        | 54 ++++++++++++++++++++++
 pkg/webtests/huma_backgrounds_misc_test.go | 20 ++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 pkg/routes/api/v2/webhook_events.go

diff --git a/pkg/routes/api/v2/webhook_events.go b/pkg/routes/api/v2/webhook_events.go
new file mode 100644
index 000000000..56ad57873
--- /dev/null
+++ b/pkg/routes/api/v2/webhook_events.go
@@ -0,0 +1,54 @@
+// Vikunja is a to-do list application to facilitate your life.
+// Copyright 2018-present Vikunja and contributors. All rights reserved.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package apiv2
+
+import (
+	"context"
+	"net/http"
+
+	"code.vikunja.io/api/pkg/config"
+	"code.vikunja.io/api/pkg/models"
+
+	"github.com/danielgtaylor/huma/v2"
+)
+
+type webhookEventsBody struct {
+	Body []string `json:"events" doc:"The events a webhook target can subscribe to."`
+}
+
+// RegisterWebhookEventRoutes wires the available-webhook-events listing onto the
+// Huma API. Like v1, the whole endpoint only exists when webhooks are enabled.
+func RegisterWebhookEventRoutes(api huma.API) {
+	if !config.WebhooksEnabled.GetBool() {
+		return
+	}
+
+	Register(api, huma.Operation{
+		OperationID: "webhooks-events-list",
+		Summary:     "List available webhook events",
+		Description: "Returns every event a webhook target can subscribe to. Use these values when creating or updating a webhook.",
+		Method:      http.MethodGet,
+		Path:        "/webhooks/events",
+		Tags:        []string{"webhooks"},
+	}, webhookEventsList)
+}
+
+func init() { AddRouteRegistrar(RegisterWebhookEventRoutes) }
+
+func webhookEventsList(_ context.Context, _ *struct{}) (*webhookEventsBody, error) {
+	return &webhookEventsBody{Body: models.GetAvailableWebhookEvents()}, nil
+}
diff --git a/pkg/webtests/huma_backgrounds_misc_test.go b/pkg/webtests/huma_backgrounds_misc_test.go
index 57a87413d..5fa412270 100644
--- a/pkg/webtests/huma_backgrounds_misc_test.go
+++ b/pkg/webtests/huma_backgrounds_misc_test.go
@@ -46,6 +46,26 @@ func TestHumaInfo(t *testing.T) {
 	assert.Contains(t, body, "available_migrators")
 }
 
+// TestHumaWebhookEvents covers the available-webhook-events listing. The route
+// is only registered when webhooks are enabled (the test config default).
+func TestHumaWebhookEvents(t *testing.T) {
+	e, err := setupTestEnv()
+	require.NoError(t, err)
+
+	t.Run("Returns the events", func(t *testing.T) {
+		rec := humaRequest(t, e, http.MethodGet, "/api/v2/webhooks/events", "", humaTokenFor(t, &testuser1), "")
+		require.Equal(t, http.StatusOK, rec.Code, "body: %s", rec.Body.String())
+
+		var events []string
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &events))
+		assert.ElementsMatch(t, models.GetAvailableWebhookEvents(), events)
+	})
+	t.Run("Unauthenticated", func(t *testing.T) {
+		rec := humaRequest(t, e, http.MethodGet, "/api/v2/webhooks/events", "", "", "")
+		assert.Equal(t, http.StatusUnauthorized, rec.Code, "body: %s", rec.Body.String())
+	})
+}
+
 // TestHumaProjectBackgroundDelete covers removing a project background. It
 // mirrors the v1 background_test.go matrix: the owner clears the background
 // (and keeps the title), a read-only user is refused.