fix(webhooks): subscribe to reconciliation events

[flemzord]

What changed

• add optional version-aware event publisher discovery
• register Reconciliation as an event publisher from v3.0.0-0
• include alpha, RC, stable, and non-SemVer development versions such as main
• keep Reconciliation v2 excluded from Webhooks subscriptions
• reconcile Webhooks when the Reconciliation module changes
• share the Reconciliation v3 threshold between topology and event publication

Why

Reconciliation v3 publishes reconciliation.alert.* events to its standard message-bus topic. The Operator configured the Reconciliation publisher, but did not expose Reconciliation through the generic EventPublisher discovery used to build Webhooks consumers. As a result, Webhooks subscribed only to Ledger and Payments and could never receive Reconciliation events.

The version gate is optional so existing publishers such as Ledger, Payments, Orchestration, and TransactionPlane keep their current behavior.

Validation

• generated manifests and objects successfully
• go fmt ./...
• go vet ./...
• CGO_ENABLED=0 go test ./api/formance.com/v1beta1 ./internal/core ./internal/resources/reconciliations ./internal/resources/webhooks ./internal/resources/brokerconsumers
• controller suite: 134/134 specs passed in serial envtest mode

The parallel all-suite run exposed an envtest concurrency flake in internal/tests; the isolated serial rerun passed all specs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5c4a49f5-360c-4b1e-9531-d7efc068c4cb

📥 Commits

Reviewing files that changed from the base of the PR and between b1c8893 and a0c80d2.

📒 Files selected for processing (8)

• api/formance.com/v1beta1/reconciliation_types.go
• api/formance.com/v1beta1/reconciliation_types_test.go
• api/formance.com/v1beta1/shared.go
• internal/core/publisher.go
• internal/core/publisher_test.go
• internal/resources/reconciliations/init.go
• internal/resources/reconciliations/init_test.go
• internal/resources/webhooks/init.go

---

Walkthrough

Changes

Versioned event publishing

Layer / File(s)	Summary
Version detection and publisher contract api/formance.com/v1beta1/reconciliation_types.go, api/formance.com/v1beta1/shared.go, api/formance.com/v1beta1/reconciliation_types_test.go	Adds VersionedEventPublisher, defines reconciliation v3 detection, and tests event-publishing decisions.
Version-aware publisher filtering internal/core/publisher.go, internal/core/publisher_test.go	Resolves stack module versions and filters versioned publishers according to PublishesEvents.
Topology selection and webhook wiring internal/resources/reconciliations/init.go, internal/resources/reconciliations/init_test.go, internal/resources/webhooks/init.go	Uses shared v3 detection for topology selection and watches Reconciliation resources for webhook reconciliation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ListEventPublishers
  participant Stack
  participant Reconciliation
  ListEventPublishers->>Stack: Resolve module version
  ListEventPublishers->>Reconciliation: PublishesEvents(version)
  Reconciliation-->>ListEventPublishers: Return inclusion decision

Loading

Possibly related PRs

• formancehq/operator#493: Both modify reconciliation v3 topology selection.

Suggested reviewers: gfyrag, numarybot

Poem

A rabbit hops through versions bright,
V3 events now take their flight.
Old publishers pause, new ones cheer,
Webhooks watch the change draw near.
“Hop-hop!” says Bunny, “the flow is clear!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: Webhooks now subscribe to Reconciliation events.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the new version-aware event publisher behavior.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/reconciliation-event-publisher

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[NumaryBot]

🛑 Changes requested — automated review

The PR introduces a version-gated check in the Reconciliation types to control whether Webhooks subscribes to Reconciliation events. One confirmed issue was found: the semver validity check does not normalize version strings that lack a leading v prefix (e.g., 2.3.1 instead of v2.3.1). Because semver.IsValid requires the v prefix, such versions are misclassified as non-SemVer/development versions and are routed down the dev-version path, which enables the Reconciliation subscription even for v2 tags — the opposite of the intended behavior. Since other version-handling code in the codebase already accommodates unprefixed tags, this inconsistency is a real risk and should be addressed before merging.

[NumaryBot]

NumaryBot posted 1 new inline finding.

Summary: #497 (comment)

[NumaryBot]

🟠 [major] Unprefixed semver versions misclassified as non-SemVer/dev

If a stack or Versions entry uses a semver tag without the leading v (e.g. 2.3.1), semver.IsValid returns false and the code falls through to the non-SemVer/dev path, treating it as a development version. This causes Webhooks to subscribe to Reconciliation v2 even though the intent of the gate is to exclude v2. Other version-handling code in the codebase accepts unprefixed semver tags, so this gate is inconsistent and can produce incorrect behavior silently.

Suggestion: Normalize the version string before calling semver.IsValid — e.g. prepend v if it is absent (if !strings.HasPrefix(ver, "v") { ver = "v" + ver }). This ensures unprefixed semver tags are correctly parsed and compared rather than being classified as development/non-SemVer versions.