feat(reconcile): add a Webhook kind

cmd/reconcile.go

@@ -23,12 +23,12 @@ func ReconcileCommand(cliConfig *Config) *cli.Command {
 			Make platform resources match a desired-state YAML file, through the admin API.
 
 			Kinds: PlatformUser (platform admins and members), Permission (custom
-			permissions), Role (platform-level roles), and Preference (platform
-			settings). Deleting a permission or a custom role needs an explicit
-			'delete: true' on its entry; nothing is deleted by omission, and a predefined
-			role cannot be deleted. A preference left out of the file resets to its
-			default. Log in as a superuser (for example the bootstrap service account)
-			with --header.
+			permissions), Role (platform-level roles), Preference (platform
+			settings), and Webhook (webhook endpoints). Deleting a permission, a
+			custom role, or a webhook needs an explicit 'delete: true' on its entry;
+			nothing is deleted by omission, and a predefined role cannot be deleted. A
+			preference left out of the file resets to its default. Log in as a superuser
+			(for example the bootstrap service account) with --header.
 
 			Use "frontier export <kind>" to print the current state in this file format.
 		`),
@@ -88,6 +88,7 @@ func buildReconcileRegistry(host, header string) (map[string]reconcile.Reconcile
 		reconcile.KindPermission:   reconcile.NewPermissionReconciler(api, header),
 		reconcile.KindRole:         reconcile.NewRoleReconciler(api, header),
 		reconcile.KindPreference:   reconcile.NewPreferenceReconciler(api, header),
+		reconcile.KindWebhook:      reconcile.NewWebhookReconciler(adminClient, header),
 	}, nil
 }
 

core/webhook/service.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"net/url"
+	"strings"
 	"time"
 
 	"github.com/raystack/frontier/pkg/server/consts"
@@ -48,6 +50,13 @@ func (s Service) CreateEndpoint(ctx context.Context, endpoint Endpoint) (Endpoin
 	if endpoint.State == "" {
 		endpoint.State = Enabled
 	}
+	endpoint.URL = strings.TrimSpace(endpoint.URL)
+	if err := validateEndpoint(endpoint); err != nil {
+		return Endpoint{}, err
+	}
+	if err := s.ensureURLIsFree(ctx, endpoint.URL, endpoint.ID); err != nil {
+		return Endpoint{}, err
+	}
 
 	// generate a random secret in hex
 	secretHex, err := crypt.NewEncryptionKeyInHex()
@@ -65,6 +74,13 @@ func (s Service) UpdateEndpoint(ctx context.Context, endpoint Endpoint) (Endpoin
 	if endpoint.ID == "" {
 		return Endpoint{}, ErrInvalidUUID
 	}
+	endpoint.URL = strings.TrimSpace(endpoint.URL)
+	if err := validateEndpoint(endpoint); err != nil {
+		return Endpoint{}, err
+	}
+	if err := s.ensureURLIsFree(ctx, endpoint.URL, endpoint.ID); err != nil {
+		return Endpoint{}, err
+	}
 	updated, err := s.eRepo.UpdateByID(ctx, endpoint)
 	if err != nil {
 		return Endpoint{}, err
@@ -73,6 +89,50 @@ func (s Service) UpdateEndpoint(ctx context.Context, endpoint Endpoint) (Endpoin
 	return updated, nil
 }
 
+// validateEndpoint checks the operator-supplied fields the reconcile flow relies
+// on. The URL is that flow's identity for an endpoint and the state is managed
+// as enabled/disabled, so the server only stores values that reconcile can
+// represent and round-trip: a valid absolute URL, and a known state.
+func validateEndpoint(endpoint Endpoint) error {
+	u, err := url.Parse(endpoint.URL)
+	if err != nil || !u.IsAbs() {
+		return fmt.Errorf("%w: url must be a valid absolute URL", ErrInvalidDetail)
+	}
+	// The server dispatches events to this URL, so restrict it to http(s). This
+	// keeps other schemes (file, gopher, ...) out of the delivery path.
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return fmt.Errorf("%w: url scheme must be http or https", ErrInvalidDetail)
+	}
+	// "https://" and "http:///path" parse as absolute http(s) URLs with an empty
+	// host. A webhook with no host to deliver to is useless, so reject it.
+	if u.Host == "" {
+		return fmt.Errorf("%w: url must include a host", ErrInvalidDetail)
+	}
+	switch endpoint.State {
+	case "", Enabled, Disabled:
+	default:
+		return fmt.Errorf("%w: state must be %q or %q", ErrInvalidDetail, Enabled, Disabled)
+	}
+	return nil
+}
+
+// ensureURLIsFree rejects a URL that another endpoint already uses. The reconcile
+// flow uses the URL as the endpoint's identity, so two endpoints sharing a URL
+// would be ambiguous. excludeID is the endpoint being updated, so it does not
+// conflict with itself.
+func (s Service) ensureURLIsFree(ctx context.Context, rawURL, excludeID string) error {
+	existing, err := s.eRepo.List(ctx, EndpointFilter{})
+	if err != nil {
+		return err
+	}
+	for _, e := range existing {
+		if e.ID != excludeID && e.URL == rawURL {
+			return fmt.Errorf("%w: url %q is already used by another webhook", ErrConflict, rawURL)
+		}
+	}
+	return nil
+}
+
 func (s Service) DeleteEndpoint(ctx context.Context, id string) error {
 	return s.eRepo.Delete(ctx, id)
 }

core/webhook/service_test.go

@@ -0,0 +1,104 @@
+package webhook_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/raystack/frontier/core/webhook"
+	"github.com/stretchr/testify/assert"
+)
+
+// fakeEndpointRepo is an in-memory webhook.EndpointRepository for service tests.
+type fakeEndpointRepo struct {
+	items []webhook.Endpoint
+}
+
+func (f *fakeEndpointRepo) Create(_ context.Context, e webhook.Endpoint) (webhook.Endpoint, error) {
+	f.items = append(f.items, e)
+	return e, nil
+}
+
+func (f *fakeEndpointRepo) UpdateByID(_ context.Context, e webhook.Endpoint) (webhook.Endpoint, error) {
+	for i := range f.items {
+		if f.items[i].ID == e.ID {
+			f.items[i] = e
+			return e, nil
+		}
+	}
+	return webhook.Endpoint{}, webhook.ErrNotFound
+}
+
+func (f *fakeEndpointRepo) Delete(_ context.Context, _ string) error { return nil }
+
+func (f *fakeEndpointRepo) List(_ context.Context, _ webhook.EndpointFilter) ([]webhook.Endpoint, error) {
+	return f.items, nil
+}
+
+func TestServiceCreateEndpointValidation(t *testing.T) {
+	t.Run("rejects a non-absolute url", func(t *testing.T) {
+		s := webhook.NewService(&fakeEndpointRepo{})
+		_, err := s.CreateEndpoint(context.Background(), webhook.Endpoint{URL: "not-a-url"})
+		assert.ErrorIs(t, err, webhook.ErrInvalidDetail)
+	})
+
+	t.Run("rejects an empty url", func(t *testing.T) {
+		s := webhook.NewService(&fakeEndpointRepo{})
+		_, err := s.CreateEndpoint(context.Background(), webhook.Endpoint{URL: "   "})
+		assert.ErrorIs(t, err, webhook.ErrInvalidDetail)
+	})
+
+	t.Run("rejects a non-http(s) scheme", func(t *testing.T) {
+		s := webhook.NewService(&fakeEndpointRepo{})
+		_, err := s.CreateEndpoint(context.Background(), webhook.Endpoint{URL: "ftp://a.example/hook"})
+		assert.ErrorIs(t, err, webhook.ErrInvalidDetail)
+	})
+
+	t.Run("rejects an http(s) url with no host", func(t *testing.T) {
+		// "https://" and "http:///path" parse as absolute http(s) URLs with an
+		// empty host, but a webhook with no host to deliver to is useless.
+		s := webhook.NewService(&fakeEndpointRepo{})
+		_, err := s.CreateEndpoint(context.Background(), webhook.Endpoint{URL: "https://"})
+		assert.ErrorIs(t, err, webhook.ErrInvalidDetail)
+	})
+
+	t.Run("rejects an unknown state", func(t *testing.T) {
+		s := webhook.NewService(&fakeEndpointRepo{})
+		_, err := s.CreateEndpoint(context.Background(), webhook.Endpoint{URL: "https://a.example/hook", State: "paused"})
+		assert.ErrorIs(t, err, webhook.ErrInvalidDetail)
+	})
+
+	t.Run("rejects a url another endpoint already uses", func(t *testing.T) {
+		repo := &fakeEndpointRepo{items: []webhook.Endpoint{{ID: "e1", URL: "https://a.example/hook"}}}
+		_, err := webhook.NewService(repo).CreateEndpoint(context.Background(), webhook.Endpoint{URL: "https://a.example/hook"})
+		assert.ErrorIs(t, err, webhook.ErrConflict)
+	})
+
+	t.Run("creates a valid endpoint, defaulting state and generating a secret", func(t *testing.T) {
+		got, err := webhook.NewService(&fakeEndpointRepo{}).CreateEndpoint(
+			context.Background(), webhook.Endpoint{URL: "https://a.example/hook"})
+		assert.NoError(t, err)
+		assert.Equal(t, webhook.Enabled, got.State) // defaulted
+		assert.Len(t, got.Secrets, 1)               // server-generated signing secret
+	})
+}
+
+func TestServiceUpdateEndpointURLUniqueness(t *testing.T) {
+	t.Run("rejects a url used by a different endpoint", func(t *testing.T) {
+		repo := &fakeEndpointRepo{items: []webhook.Endpoint{
+			{ID: "e1", URL: "https://a.example/hook", State: webhook.Enabled},
+			{ID: "e2", URL: "https://b.example/hook", State: webhook.Enabled},
+		}}
+		_, err := webhook.NewService(repo).UpdateEndpoint(context.Background(),
+			webhook.Endpoint{ID: "e2", URL: "https://a.example/hook", State: webhook.Enabled})
+		assert.ErrorIs(t, err, webhook.ErrConflict)
+	})
+
+	t.Run("lets an endpoint keep its own url", func(t *testing.T) {
+		repo := &fakeEndpointRepo{items: []webhook.Endpoint{
+			{ID: "e1", URL: "https://a.example/hook", State: webhook.Enabled},
+		}}
+		_, err := webhook.NewService(repo).UpdateEndpoint(context.Background(),
+			webhook.Endpoint{ID: "e1", URL: "https://a.example/hook", State: webhook.Disabled})
+		assert.NoError(t, err)
+	})
+}

docs/content/docs/reconcile.mdx

@@ -194,6 +194,45 @@ spec:
 - Export writes only the preferences whose value differs from the default, so settings at
   their default stay out of the file.
 
+## The Webhook kind
+
+`Webhook` manages webhook endpoints: a URL, the events it subscribes to, and whether it is
+enabled. The URL is the identity and never changes.
+
+```yaml
+apiVersion: v1
+kind: Webhook
+spec:
+  - url: https://hooks.example.org/frontier
+    description: Ops notifications
+    subscribed_events:
+      - app.user.created
+      - app.group.created
+    state: enabled
+  - url: https://old.example.org/frontier
+    delete: true
+```
+
+- The URL must be a valid absolute HTTP(S) URL, and it is the identity. If two endpoints on the
+  server share a URL, the identity is ambiguous: the plan fails and names the ids so you can
+  remove the extra one by hand.
+- `subscribed_events` is the full set of events the endpoint receives, compared as a set. An
+  empty list, or leaving the field out, means every event, which is the server default. It is
+  the complete desired set, not a keep-if-omitted field: dropping it sets the endpoint to all
+  events rather than keeping the current set, and export always writes it, showing `[]` for an
+  all-events endpoint. `description` and `state` (`enabled` or `disabled`) follow the same one
+  field model: a value you write is used as-is, and leaving the field out converges it to the
+  default. Description defaults to empty, so dropping it clears any description on the server;
+  state defaults to `enabled`, so dropping it re-enables the endpoint.
+- Every endpoint on the server must appear in the file, kept or marked `delete: true`. An
+  endpoint that is missing fails the plan; nothing is deleted just because it is missing.
+- The signing secret is server-owned. The server generates it when the endpoint is created
+  and never returns it on read, so it is not part of the file, never shows up in a plan, and
+  can never appear in an export.
+- Export leaves out `state` when it is the default `enabled` and `description` when it is
+  empty, so reconciling an export plans nothing, and headers and metadata set through other
+  tools are carried through an update untouched.
+
 ## Running it
 
 Log in as a superuser. The bootstrap service user exists for exactly this; its client id
@@ -236,7 +275,7 @@ The kind argument is case-insensitive and accepts a plural, so `platformuser` an
 
 ## More kinds
 
-This page covers `PlatformUser`, `Permission`, `Role`, and `Preference`. The design and
+This page covers `PlatformUser`, `Permission`, `Role`, `Preference`, and `Webhook`. The design and
 the rules every kind follows live in
 [RFC 0001](https://github.com/raystack/frontier/blob/main/docs/rfcs/0001-declarative-reconcile.md),
 which also lists the kinds proposed next. The flag reference for both commands is in the

docs/content/docs/reference/cli.mdx

@@ -34,7 +34,7 @@ List of supported environment variables
 Export the current state of a kind as a desired-state YAML file, printed to
 stdout. The output is the format `frontier reconcile` reads: reconciling it
 changes nothing. Supported kinds: `PlatformUser`, `Permission`, `Role`,
-`Preference`. See the
+`Preference`, `Webhook`. See the
 [Reconcile guide](../reconcile.md) for the file format and the flow.
 
 ```
@@ -249,10 +249,11 @@ View a project
 Make platform resources match a desired-state YAML file, through the admin
 API. Supported kinds: `PlatformUser` (anyone listed is added, anyone not
 listed is removed), `Permission` (custom permissions), `Role`
-(platform-level roles), and `Preference` (platform settings, where a setting
-left out of the file resets to its default). Deleting a permission or a custom
-role needs an explicit `delete: true` on its entry; nothing is deleted by
-omission, and a predefined role cannot be deleted. Use
+(platform-level roles), `Preference` (platform settings, where a setting
+left out of the file resets to its default), and `Webhook` (webhook endpoints).
+Deleting a permission, a custom role, or a webhook needs an explicit
+`delete: true` on its entry; nothing is deleted by omission, and a predefined
+role cannot be deleted. Use
 `frontier export` to print the current state in this file format, and see the
 [Reconcile guide](../reconcile.md) for the full flow.
 

internal/api/v1beta1connect/webhook.go

@@ -2,6 +2,7 @@ package v1beta1connect
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	"connectrpc.com/connect"
@@ -11,6 +12,22 @@ import (
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
+// webhookErrCode maps a webhook service error to the connect status code the
+// caller should see, so a bad request reads as invalid-argument rather than an
+// internal error.
+func webhookErrCode(err error) connect.Code {
+	switch {
+	case errors.Is(err, webhook.ErrInvalidDetail), errors.Is(err, webhook.ErrInvalidUUID):
+		return connect.CodeInvalidArgument
+	case errors.Is(err, webhook.ErrConflict):
+		return connect.CodeAlreadyExists
+	case errors.Is(err, webhook.ErrNotFound):
+		return connect.CodeNotFound
+	default:
+		return connect.CodeInternal
+	}
+}
+
 func (h *ConnectHandler) CreateWebhook(ctx context.Context, req *connect.Request[frontierv1beta1.CreateWebhookRequest]) (*connect.Response[frontierv1beta1.CreateWebhookResponse], error) {
 	var metaDataMap metadata.Metadata
 	if req.Msg.GetBody().GetMetadata() != nil {
@@ -25,7 +42,7 @@ func (h *ConnectHandler) CreateWebhook(ctx context.Context, req *connect.Request
 		Metadata:         metaDataMap,
 	})
 	if err != nil {
-		return nil, connect.NewError(connect.CodeInternal, fmt.Errorf("CreateWebhook: url=%s: %w", req.Msg.GetBody().GetUrl(), err))
+		return nil, connect.NewError(webhookErrCode(err), fmt.Errorf("CreateWebhook: url=%s: %w", req.Msg.GetBody().GetUrl(), err))
 	}
 	endpointPb, err := toProtoWebhookEndpoint(endpoint)
 	if err != nil {
@@ -53,7 +70,7 @@ func (h *ConnectHandler) UpdateWebhook(ctx context.Context, req *connect.Request
 		Metadata:         metaDataMap,
 	})
 	if err != nil {
-		return nil, connect.NewError(connect.CodeInternal, fmt.Errorf("UpdateWebhook: webhook_id=%s url=%s: %w", webhookID, req.Msg.GetBody().GetUrl(), err))
+		return nil, connect.NewError(webhookErrCode(err), fmt.Errorf("UpdateWebhook: webhook_id=%s url=%s: %w", webhookID, req.Msg.GetBody().GetUrl(), err))
 	}
 	endpointPb, err := toProtoWebhookEndpoint(endpoint)
 	if err != nil {
@@ -68,7 +85,7 @@ func (h *ConnectHandler) ListWebhooks(ctx context.Context, req *connect.Request[
 	filter := webhook.EndpointFilter{}
 	endpoints, err := h.webhookService.ListEndpoints(ctx, filter)
 	if err != nil {
-		return nil, connect.NewError(connect.CodeInternal, fmt.Errorf("ListWebhooks: %w", err))
+		return nil, connect.NewError(webhookErrCode(err), fmt.Errorf("ListWebhooks: %w", err))
 	}
 	var webhooks []*frontierv1beta1.Webhook
 	for _, endpoint := range endpoints {
@@ -88,7 +105,7 @@ func (h *ConnectHandler) DeleteWebhook(ctx context.Context, req *connect.Request
 
 	err := h.webhookService.DeleteEndpoint(ctx, webhookID)
 	if err != nil {
-		return nil, connect.NewError(connect.CodeInternal, fmt.Errorf("DeleteWebhook: webhook_id=%s: %w", webhookID, err))
+		return nil, connect.NewError(webhookErrCode(err), fmt.Errorf("DeleteWebhook: webhook_id=%s: %w", webhookID, err))
 	}
 	return connect.NewResponse(&frontierv1beta1.DeleteWebhookResponse{}), nil
 }

internal/reconcile/role.go

@@ -167,6 +167,26 @@ func sortedCopy(in []string) []string {
 	return out
 }
 
+// uniqueSorted returns the input as a sorted, deduplicated slice. It is used for
+// set-valued fields whose input can hold duplicates (a hand-written list may
+// repeat a value), so the compare and the value sent to the server both use the
+// same canonical set.
+func uniqueSorted(in []string) []string {
+	if len(in) == 0 {
+		return nil
+	}
+	set := make(map[string]struct{}, len(in))
+	for _, v := range in {
+		set[v] = struct{}{}
+	}
+	out := make([]string, 0, len(set))
+	for v := range set {
+		out = append(out, v)
+	}
+	sort.Strings(out)
+	return out
+}
+
 func stringSetsEqual(a, b []string) bool {
 	if len(a) != len(b) {
 		return false