feat: Webhook caching and assorted improvements

[xernobyl]

Description

This PR adds webhook list/GetByID caching with singleflight, retrying webhook enqueue with exponential backoff, consolidates observability into a single Metrics type, and aligns repository naming and integration tests with local Docker setup.

Changes

Webhook caching

• pkg/cache/loader_cache.go: New generic LoaderCache (LRU + singleflight) for cache-on-miss with request coalescing.
• internal/service/caching_webhooks_repo.go: CachingWebhooksRepository decorator caches ListEnabledForEventType and GetByID; invalidates on Create/Update/Delete.
• Config: WEBHOOK_CACHE_SIZE (default 4096). Documented in environment variables and metrics docs.

Retrying webhook enqueue

• internal/service/retrying_webhook_inserter.go: RetryingWebhookDispatchInserter wraps River client with exponential backoff + jitter on InsertMany failures.
• Config: WEBHOOK_ENQUEUE_MAX_RETRIES, WEBHOOK_ENQUEUE_INITIAL_BACKOFF, WEBHOOK_ENQUEUE_MAX_BACKOFF (defaults: 3, 100ms, 2s). Documented in env and event-pipeline docs.
• Observability: hub_webhook_enqueue_retries_total counter for retry metrics.

Observability

• internal/observability/aggregate.go: New Metrics struct aggregating Events, Webhooks, and Cache metrics.
• internal/observability/cache.go: Cache metrics (hit/miss by cache name).
• cmd/api/app.go: Uses single observability.NewMetrics(); wiring updated for cache metrics and retrying inserter.

Repository naming and docs

• Webhooks: repository.WebhooksRepository (struct) renamed to DBWebhooksRepository; constructor NewDBWebhooksRepository. Interface remains service.WebhooksRepository.
• Feedback records: Same pattern — DBFeedbackRecordsRepository / NewDBFeedbackRecordsRepository.
• AGENTS.md: New “Repository pattern” bullet (interface in service, DB impl in repository, optional caching decorator).

Integration tests

• tests/integration_test.go: Use DATABASE_URL from environment when set (e.g. .env with port 5433); otherwise default localhost:5432/test_db for CI.
• Makefile: make tests exports .env before running go test, so local runs hit the same Postgres as dev.

Other

• .golangci.yml: Lint/config tweaks as needed.
• Docs: environment-variables.mdx, metrics.mdx, and related reference docs updated for new config and metrics.

Testing

• Unit tests
  • pkg/cache: go test ./pkg/cache/... -count=1 ✅
  • internal/service: go test ./internal/service/... -count=1 ✅ (includes caching_webhooks_repo and retrying_webhook_inserter)
  • internal/repository: go test ./internal/repository/... -count=1 ✅
• Integration tests (Postgres required, e.g. make docker-up; use same port as in .env):
  • make tests ✅ (loads .env, all tests pass)

Evidence:

make tests
# PASS; ok  github.com/formbricks/hub/tests  <1s

Checklist

• Code follows project style (make fmt, make lint).
• New behavior covered by unit/integration tests.
• Docs updated (env vars, metrics, AGENTS.md repository pattern).
• Related issues linked (if any).

[github-actions]

✱ Stainless preview builds

This PR will update the hub SDKs with the following commit message.

feat: Webhook caching and assorted improvements

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hub-openapi studio · code · diff

Your SDK built successfully.
generate ✅ (prev: generate ⚠️)

✅ hub-typescript studio · code · diff

Your SDK built successfully.
generate ✅ (prev: generate ⚠️) → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hub-typescript/3ec6d1d502c2bc9e213c2c499b3004179d14eeb7/dist.tar.gz

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-02-20 17:21:41 UTC